@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/api/effect/collectors.ts

@@ -0,0 +1,103 @@
+import * as Effect from "effect/Effect"
+import type {
+    ReactionCollectorOptions as SharedReactionCollectorOptions,
+    ReactionCollectorResult,
+    CollectorOptions as SharedCollectorOptions,
+    CollectorResult,
+    CollectorFailure,
+} from "#sdk/collectors"
+import type { Message, MessageCore } from "#sdk/messages"
+
+/** Choose reaction collection limits and an optional callback for each accepted addition.
+ * The callback executes with the services available when collection is registered
+ *
+ * @category Events and collectors
+ */
+export interface ReactionCollectorOptions<E = never, R = never> extends SharedReactionCollectorOptions {
+    /** Run once per accepted addition, sequentially, before continuing collection.
+     * Failures and defects while active fail collection with CollectorError handler, whose cause is the original failure or defect.
+     * The failure is also reported to the client-level onError with kind collector, the message IDs and the full Cause, or logged at Error.
+     * Stop, timeout, idle completion, scope closure, recovery and shutdown interrupt active work and await its finalizers.
+     * Uninterruptible work can delay closure. Do not await this collector's completion inside its handler.
+     * Already-dispatched effects are not rolled back. Callbacks are never retried
+     */
+    readonly onReaction?: (reaction: import("#sdk/reactions").MessageReaction) => Effect.Effect<unknown, E, R>
+}
+
+/** Choose message collection limits and an optional callback for each accepted message.
+ * The callback executes with the services available when collection is registered
+ *
+ * @category Events and collectors
+ */
+export interface CollectorOptions<
+    E = never,
+    R = never,
+    M extends MessageCore = Message,
+> extends SharedCollectorOptions<M> {
+    /** Run once per accepted message ID, sequentially, after filtering and stored-byte limit checks.
+     * Failures and defects while active fail collection with CollectorError handler, whose cause is the original failure or defect.
+     * The failure is also reported to the client-level onError with kind collector, the message IDs and the full Cause, or logged at Error.
+     * Stop, timeout, idle completion, scope closure, recovery and shutdown interrupt active work and await its finalizers.
+     * Uninterruptible work can delay closure. Do not await this collector's completion or client shutdown inside its handler.
+     * Already-dispatched effects are not rolled back. Callbacks are never retried
+     */
+    readonly onMessage?: (message: M) => Effect.Effect<unknown, E, R>
+}
+
+/** A running message collector registered in a Scope.
+ * Use close to end collection and result to receive its result after cleanup
+ *
+ * @category Events and collectors
+ */
+export interface Collector<M extends MessageCore = Message> {
+    /**
+     * Stop accepting messages now, keeping accepted messages for a successful partial result.
+     * Repeated calls preserve whichever terminal outcome was recorded first.
+     * Use result to await callback cleanup and read the collection
+     *
+     * @remarks
+     * Stops collection when the Effect executes
+     */
+    close(): Effect.Effect<void>
+    /**
+     * Wait for the final frozen collection result after timer, queue, filter, listener and callback cleanup.
+     * Idle, timeout or stop can succeed with no messages or a partial collection.
+     * Collection cancellation, filter or callback failure, overflow, gateway loss and client closure fail without partial messages.
+     * Multiple or later waiters receive the same collection outcome.
+     * Cancelling this wait affects only the waiter, not collection.
+     * Keeping the handle or successful result keeps its message snapshots in memory
+     *
+     * @remarks
+     * Defects keep their Cause
+     */
+    result(): Effect.Effect<CollectorResult<M>, CollectorFailure>
+}
+
+/** A running reaction collector registered in a Scope.
+ * Use close to end collection and result to receive its result after cleanup
+ *
+ * @category Events and collectors
+ */
+export interface ReactionCollector {
+    /**
+     * Stop accepting additions now and keep accepted observations for a successful partial result.
+     * Repeated calls preserve the first recorded outcome.
+     * Use result to await callback cleanup and read the observations
+     *
+     * @remarks
+     * Stops collection when the Effect executes
+     */
+    close(): Effect.Effect<void>
+    /**
+     * Wait for the final frozen reaction result after queue, timer, filter, listener and callback cleanup.
+     * Idle, timeout or stop can succeed with empty or partial observations.
+     * Collection cancellation, filter or callback failure, overflow, gateway loss and client shutdown fail without partial observations.
+     * Multiple or later waiters receive the same outcome.
+     * Cancelling this wait affects only the waiter, not collection.
+     * Keeping the handle or successful result retains its snapshots in memory
+     *
+     * @remarks
+     * Defects keep their Cause
+     */
+    result(): Effect.Effect<ReactionCollectorResult, CollectorFailure>
+}

package/src/api/effect/commands.ts

@@ -0,0 +1,87 @@
+import { nativeCommands } from "#sdk/native-commands"
+
+/**
+ * Define text commands, parse their arguments and attach them to an existing client.
+ * The simplest route is runBot's commands option. Creation, registration and help return their result directly and
+ * throw ConfigurationError for misuse, so a misconfigured router fails at startup.
+ * Commands listen through one bounded messageCreate subscription in the caller's Scope when attach executes.
+ * The router does not connect the client or create a separate SDK runtime.
+ * Guards, cooldown keys, unmatched feedback and handler Effects remain application-owned, with built-in `guards` for common checks.
+ * The router does not retry failures, and it replies on its own only when `onReject: "reply"` is selected.
+ * Groups optionally organize command paths and help pages.
+ * Flat commands remain independent, and each protected command still needs its own guard
+ *
+ * @example
+ * ```ts
+ * import { commands, type Client } from "@neontechspace/fluxerly/effect"
+ * export function commandGroupExample(client: Client) {
+ *     return commands
+ *         .create({ prefix: "!" })
+ *         .registerGroup({ name: "tools", aliases: ["t"] })
+ *         .register({ name: "ping", execute: ({ reply }) => reply("Pong") }, { group: ["tools"] })
+ *         .attach(client)
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { commands, type Client } from "@neontechspace/fluxerly/effect"
+ *
+ * export const installPing = (client: Client) =>
+ *     commands
+ *         .create({
+ *             prefix: "!",
+ *             parse: commands.parseQuoted,
+ *             onUnmatched: ({ reply }, unmatched) => {
+ *                 if (unmatched._tag !== "CommandUnknownName") return Effect.void
+ *                 const hint = unmatched.suggestion === undefined ? "" : `. Closest known command: ${unmatched.suggestion}`
+ *                 return reply(`Unknown command: ${unmatched.name}${hint}`)
+ *             },
+ *         })
+ *         .register({ name: "ping", execute: ({ reply }) => reply("Pong") })
+ *         .attach(client)
+ * ```
+ * Argument schemas are optional definitions of the values a command expects.
+ * Guards see raw input first. Conversion failures give rejection feedback without consuming a cooldown.
+ * The execute callback receives inferred frozen values alongside unchanged args
+ *
+ * @example
+ * ```ts
+ * import { commands, type Client } from "@neontechspace/fluxerly/effect"
+ *
+ * export function typedCommandExample(client: Client) {
+ *     return commands
+ *         .create({ prefix: "!", parse: commands.parseQuoted, onReject: "reply" })
+ *         .register({
+ *             name: "repeat",
+ *             arguments: {
+ *                 mode: { type: "choice", choices: ["fast", "slow"] },
+ *                 count: { type: "integer", min: 1, max: 5, default: 1 },
+ *                 note: { type: "text", optional: true, rest: true },
+ *             },
+ *             cooldown: { durationMs: 10_000, per: "user" },
+ *             execute: ({ reply, values }) => reply(`${values.count} / ${values.mode} / ${values.note ?? "No note"}`),
+ *         })
+ *         .attach(client)
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { type Client, type NativePrefixCommandRouter } from "@neontechspace/fluxerly/effect"
+ *
+ * export function commandHelpExample(client: Client, router: NativePrefixCommandRouter, channelId: string) {
+ *     const pages = router.help({ prefix: "!", maxLength: 1_000, include: (command) => command.name !== "admin" })
+ *     // Visibility is not authorization. Each command still needs its own policy
+ *     return Effect.forEach(pages, (content) => client.messages.send(channelId, { content, allowedMentions: {} }), {
+ *         discard: true,
+ *     })
+ *     // Earlier pages remain sent if a later send fails or is interrupted. No retries occur
+ * }
+ * ```
+ *
+ * @category Commands
+ */
+export const commands = nativeCommands

package/src/api/effect/direct-messages.ts

@@ -0,0 +1,119 @@
+import type {
+    DirectMessageChannel,
+    DirectMessageGroupEdit,
+    DirectMessageLatestMessages,
+    UserOperationFailure,
+    UserOperationOptions,
+} from "#sdk/users"
+import type * as Effect from "effect/Effect"
+import type { SendError } from "#sdk/message-errors"
+import type { Message, MessageCore, ReplyInput, SendOptions } from "#sdk/messages"
+
+/** Open private conversations, send messages or manage existing groups.
+ * Methods return Effects with the client's default deadline (rest.defaultTimeoutMs, 30,000 ms unless configured) and at most two eligible transient read retries.
+ * Writes retry only confirmed rate-limit rejection, never an unknown outcome. No gateway connection is required.
+ * Cancellation and unexpected faults remain in Cause rather than becoming UserOperationError
+ *
+ * @category Users and DMs
+ */
+export interface DirectMessages<M extends MessageCore = Message> {
+    /**
+     * Open or reopen a one-to-one conversation with a user, then send a message.
+     * A plain string sends only that text, as shorthand for `{ content }`.
+     * The whole operation uses one deadline, and mentions are disabled by default.
+     * Message metadata and data bytes are prepared before opening the conversation.
+     * File and stream sources are captured, not copied, and read later when uploads start, using messages.send's size, upload-budget and cleanup rules.
+     * An inline multipart 429 does not replay file or stream sources.
+     * MessageError with outcome notDispatched does not mean opening the conversation was undone.
+     * A send with an unknown outcome is never repeated automatically.
+     * The opened conversation is cached under the same conditions as open.
+     * Reply references are not accepted here.
+     * Use messages.reply with an existing channel and message reference
+     *
+     * @example
+     * ```ts
+     * import { Effect } from "effect"
+     * import type { Client } from "@neontechspace/fluxerly/effect"
+     * export const notifyUserExample = (client: Client, userId: string) => Effect.gen(function* () {
+     *     const user = yield* client.users.fetch(userId)
+     *     return yield* client.directMessages.send(user.id, { content: `Hello ${user.displayName ?? user.username}` })
+     * })
+     * ```
+     */
+    send(userId: string, input: ReplyInput | string, options?: SendOptions): Effect.Effect<M, SendError>
+    /**
+     * Look up a private channel in the optional cache using its decimal ID, without a request.
+     * A hit may be stale and becomes more recently used without extending its age.
+     * A miss produces undefined.
+     * An invalid ID is misuse: The default API throws UserOperationError with reason input and the native API dies with it.
+     * A closing or closed client has no cache, so the result is undefined
+     */
+    get(id: string): Effect.Effect<DirectMessageChannel | undefined>
+    /**
+     * Open or reopen a one-to-one conversation with the selected user.
+     * The result is a private channel, not proof a message can be delivered.
+     * Privacy checks can still prevent sending after opening succeeds.
+     * With the direct-message cache enabled, the channel ID is unknown until the response arrives, so some concurrent direct-message cache changes keep the result out of the cache.
+     * Examples are a directMessages.fetch call and a direct-message update event
+     */
+    open(userId: string, options?: UserOperationOptions): Effect.Effect<DirectMessageChannel, UserOperationFailure>
+    /**
+     * Fetch a private channel by decimal ID.
+     * A community-channel response is rejected as invalid.
+     * With the direct-message cache enabled, a concurrent fetch of another private channel ID does not keep this result from being stored, unless more than 256 private channel IDs are in flight at once
+     */
+    fetch(id: string, options?: UserOperationOptions): Effect.Effect<DirectMessageChannel, UserOperationFailure>
+    /**
+     * Fetch this bot's currently open one-to-one and group conversations.
+     * Personal notes are excluded.
+     * The list is neither an atomic snapshot nor complete message history.
+     * Enabled cache replacement is skipped when a later targeted request or channel observation conflicts
+     */
+    fetchAll(options?: UserOperationOptions): Effect.Effect<readonly DirectMessageChannel[], UserOperationFailure>
+    /**
+     * Fetch the latest messages for 1–100 selected, distinct private channel IDs through Fluxer's batch endpoint.
+     * IDs are copied by index when execution starts.
+     * This does not enumerate conversations or fill a cache.
+     * A null entry does not prove an empty channel or denied access.
+     * The omittedChannelIds field separately lists requested IDs that Fluxer did not return.
+     * Do not treat omission as null, an empty channel or denied access.
+     * The batch uses POST and is not retried after a dispatched failure with an unknown outcome, even though it reads data
+     */
+    fetchLatestMessages(
+        channelIds: readonly string[],
+        options?: UserOperationOptions,
+    ): Effect.Effect<DirectMessageLatestMessages<M>, UserOperationFailure>
+    /**
+     * Change supplied settings of an existing group conversation.
+     * A null name clears it, and omitted fields remain unchanged.
+     * Fluxer enforces member and owner permissions.
+     * A failed response does not guarantee rollback.
+     * Enabled cache invalidation normally stays scoped to this conversation.
+     * A cache-wide conflict check can also prevent older in-flight results from being stored
+     */
+    editGroup(
+        id: string,
+        input: DirectMessageGroupEdit,
+        options?: UserOperationOptions,
+    ): Effect.Effect<DirectMessageChannel, UserOperationFailure>
+    /**
+     * Close a one-to-one conversation for this bot, or leave a group conversation.
+     * Another recipient's conversation is not erased.
+     * If the group owner leaves, ownership may transfer.
+     * Enabled cache invalidation normally stays scoped to this conversation.
+     * A cache-wide conflict check can also prevent older in-flight results from being stored
+     */
+    close(id: string, options?: UserOperationOptions): Effect.Effect<void, UserOperationFailure>
+    /**
+     * Remove a group recipient as owner, or remove the bot itself.
+     * This does not request deletion of that user's messages.
+     * If the last recipient leaves, Fluxer deletes the group.
+     * Enabled cache invalidation normally stays scoped to this conversation.
+     * A cache-wide conflict check can also prevent older in-flight results from being stored
+     */
+    removeRecipient(
+        id: string,
+        userId: string,
+        options?: UserOperationOptions,
+    ): Effect.Effect<void, UserOperationFailure>
+}

package/src/api/effect/discovery.ts

@@ -0,0 +1,87 @@
+import type {
+    DiscoveryApplication,
+    DiscoveryApplicationInput,
+    DiscoveryApplicationEdit,
+    DiscoveryCategory,
+    DiscoverySearchPage,
+    DiscoverySearchQuery,
+    DiscoveryStatus,
+} from "#sdk/discovery"
+import type * as Effect from "effect/Effect"
+import type { GuildOperationFailure, GuildOperationOptions } from "#sdk/guilds"
+
+/** Search Fluxer's public community directory or manage a community's listing application.
+ * This is separate from instance endpoint discovery. HTTP requests share guild limits and directory data is not cached.
+ * Effects start when executed and can be run again, using the caller's services without requiring gateway readiness. The total deadline defaults to the client's rest.defaultTimeoutMs, 30,000 ms unless configured.
+ * Reads retry transient transport and HTTP 500/502/503/504 failures at most twice. Writes retry only confirmed 429 rejections.
+ * Input, HTTP and malformed-response failures use GuildOperationError. Closing clients use ClientClosedError.
+ * Interruption waits for owned cleanup. Defects retain Cause.
+ * Application writes may publish or unpublish a listing, invalidate guild snapshots and cannot promise rollback.
+ * There is no hidden eligibility read, automatic resubmission, review approval or directory-joining operation
+ *
+ * @category Guilds and members
+ */
+export interface Discovery {
+    /**
+     * Fetch one page from the current public community directory.
+     * The limit option defaults to 24, and offset defaults to 0.
+     * Pages can change between reads, so offset-based scans are not a stable snapshot.
+     * This neither joins a community nor caches its directory entry, and needs no gateway connection.
+     * Eligible read failures are retried as described for this namespace
+     */
+    search(
+        query?: DiscoverySearchQuery,
+        options?: GuildOperationOptions,
+    ): Effect.Effect<DiscoverySearchPage, GuildOperationFailure>
+    /**
+     * Fetch a community's current directory eligibility and application state.
+     * Use a decimal guild ID with ManageGuild permission.
+     * A result with eligible false can mean discovery is disabled or the member threshold is unmet, without distinguishing them.
+     * Eligibility can change before application.
+     * Reviewed or removed applications include their available reasons
+     */
+    fetchStatus(guildId: string, options?: GuildOperationOptions): Effect.Effect<DiscoveryStatus, GuildOperationFailure>
+    /**
+     * Fetch directory category IDs and Fluxer's category labels in provider order.
+     * This requires an authenticated client, not membership of a particular community or ManageGuild.
+     * No category copy is kept
+     */
+    fetchCategories(options?: GuildOperationOptions): Effect.Effect<readonly DiscoveryCategory[], GuildOperationFailure>
+    /**
+     * Submit a community's application to the public directory.
+     * ManageGuild, enabled discovery and current Fluxer eligibility are required.
+     * An existing pending or approved application fails remotely.
+     * Eligible verified or partnered communities may be approved immediately.
+     * The returned stored application does not guarantee approval or search visibility.
+     * An unknown outcome may already have submitted or published the listing.
+     * Check fetchStatus before trying again
+     */
+    apply(
+        guildId: string,
+        input: DiscoveryApplicationInput,
+        options?: GuildOperationOptions,
+    ): Effect.Effect<DiscoveryApplication, GuildOperationFailure>
+    /**
+     * Change supplied fields of a pending or approved directory application.
+     * ManageGuild and enabled discovery are required.
+     * At least one field must be supplied, and omitted fields remain unchanged.
+     * Tags use the input type's normalization and replacement rules.
+     * No old application is fetched or merged automatically.
+     * Updates to an approved listing can become public, while search-index updates can lag or partially fail
+     */
+    edit(
+        guildId: string,
+        input: DiscoveryApplicationEdit,
+        options?: GuildOperationOptions,
+    ): Effect.Effect<DiscoveryApplication, GuildOperationFailure>
+    /**
+     * Withdraw a pending application or remove an approved directory listing.
+     * ManageGuild and enabled discovery are required.
+     * HTTP 204 succeeds with no value.
+     * A missing application is a remote error, not an assumed successful no-op.
+     * Fluxer removes the application record and may separately remove its feature or search entry.
+     * The community and its members remain, and the prior application is not restored.
+     * An unknown or partial outcome needs remote inspection and may require operator recovery, not blind replay
+     */
+    withdraw(guildId: string, options?: GuildOperationOptions): Effect.Effect<void, GuildOperationFailure>
+}

package/src/api/effect/emojis.ts

@@ -0,0 +1,108 @@
+import type {
+    GuildEmoji,
+    ExpressionReference,
+    ExpressionMetadata,
+    ExpressionSourceGuild,
+    EmojiCreate,
+    EmojiEdit,
+    ExpressionBatch,
+    ExpressionDeleteOptions,
+} from "#sdk/expressions"
+import type * as Effect from "effect/Effect"
+import type { GuildOperationFailure, GuildOperationOptions, ModerationOptions } from "#sdk/guilds"
+
+/** Read, upload, rename, clone or delete custom emoji.
+ * Methods return Effects and share guild HTTP concurrency limits, deadlines and GuildOperationError failures.
+ * Reads retry eligible transient failures at most twice. Writes retry only confirmed 429 rejections.
+ * Input, permission, 404 and malformed responses do not retry. Unknown outcomes may leave writes applied.
+ * Effects start when executed, use the caller's services and await cleanup on interruption. Defects remain in Cause.
+ * Closing clients fail with ClientClosedError. Snapshots are frozen and HTTP success is not gateway acknowledgement
+ *
+ * @category Emoji and stickers
+ */
+export interface Emojis {
+    /**
+     * Look up cached emoji metadata using decimal guildId and id, without an HTTP request.
+     * The result is undefined when caching is disabled or the entry is absent, expired or invalidated by a conflicting change.
+     * A hit becomes more recently used without extending expiry.
+     * An invalid ID is misuse: The default API throws GuildOperationError with reason input and the native API dies with it.
+     * A closing or closed client has no cache, so the result is undefined
+     */
+    get(target: ExpressionReference): Effect.Effect<GuildEmoji | undefined>
+    /**
+     * Fetch a community's emoji list in Fluxer's order, without pagination.
+     * The list can change after the response and is not an ongoing completeness guarantee.
+     * An enabled metadata cache can retain results, but not image bytes or creator accounts
+     */
+    fetchAll(
+        guildId: string,
+        options?: GuildOperationOptions,
+    ): Effect.Effect<readonly GuildEmoji[], GuildOperationFailure>
+    /**
+     * Fetch minimal emoji metadata by decimal ID, without requiring source-community membership.
+     * This read does not populate the cache
+     */
+    fetchMetadata(id: string, options?: GuildOperationOptions): Effect.Effect<ExpressionMetadata, GuildOperationFailure>
+    /**
+     * Fetch the public presentation of the community that owns a custom emoji with this decimal ID: Its ID, name, icon hash and badges.
+     * Fluxer answers when the source community is discoverable or the bot is a member of it.
+     * A private source community the bot is not in, an unavailable community or an unknown emoji fails with GuildOperationError
+     * whose apiError.code is unknownResource, without revealing which case applies.
+     * This read does not populate the cache, and the result does not update when the community changes
+     */
+    fetchSource(
+        id: string,
+        options?: GuildOperationOptions,
+    ): Effect.Effect<ExpressionSourceGuild, GuildOperationFailure>
+    /**
+     * Upload one community emoji and return its metadata.
+     * Inputs are copied when execution starts.
+     * No image URL is fetched automatically.
+     * Fluxer checks image format, dimensions, permissions and capacity.
+     * A write with an unknown outcome is not replayed
+     */
+    create(
+        guildId: string,
+        input: EmojiCreate,
+        options?: ModerationOptions,
+    ): Effect.Effect<GuildEmoji, GuildOperationFailure>
+    /**
+     * Upload 1–50 community emojis in one batch and return separate successes and failures.
+     * The input array is copied by index, then its entries are copied when execution starts.
+     * Some uploads can succeed while others fail.
+     * No rollback or automatic chunking is performed.
+     * Failures named by duplicate emoji names cannot be matched reliably to input positions.
+     * After an unknown outcome, fetch fresh remote data rather than blindly replaying the batch
+     */
+    createMany(
+        guildId: string,
+        input: readonly EmojiCreate[],
+        options?: ModerationOptions,
+    ): Effect.Effect<ExpressionBatch<GuildEmoji>, GuildOperationFailure>
+    /**
+     * Copy an emoji into a community by its source ID, using Fluxer's server-side copy.
+     * Source metadata is preserved.
+     * Fluxer enforces source copying restrictions
+     */
+    clone(
+        guildId: string,
+        sourceId: string,
+        options?: ModerationOptions,
+    ): Effect.Effect<GuildEmoji, GuildOperationFailure>
+    /**
+     * Rename a community emoji without changing its image or fetching its old metadata first
+     */
+    edit(
+        target: ExpressionReference,
+        input: EmojiEdit,
+        options?: ModerationOptions,
+    ): Effect.Effect<GuildEmoji, GuildOperationFailure>
+    /**
+     * Remove an emoji, succeeding with no value after HTTP 204.
+     * Retained metadata is invalidated.
+     * A missing target is an error, not proof of an earlier deletion.
+     * The purge option defaults to false.
+     * Setting it to true also queues irreversible media removal, subject to Fluxer's restrictions
+     */
+    delete(target: ExpressionReference, options?: ExpressionDeleteOptions): Effect.Effect<void, GuildOperationFailure>
+}

package/src/api/effect/events.ts

@@ -0,0 +1,92 @@
+import * as Deferred from "effect/Deferred"
+import * as Effect from "effect/Effect"
+import type { EventSource } from "#sdk/internal/events"
+import { EventOverflowError } from "#sdk/message-errors"
+import type { EventInvocation, HandlerOptions } from "#sdk/events"
+import type { Message, MessageCore } from "#sdk/messages"
+import { type FailureReport } from "./failures.js"
+
+/**
+ * An event subscription registered in a Scope, independent of the client's connection.
+ * Use close to request a stop and waitForClose to wait for handler cleanup
+ *
+ * @category Events and collectors
+ */
+export interface Subscription {
+    /** Identifier of this subscription, such as messageCreate#3, used in failure reports and log records */
+    readonly id: string
+    /**
+     * Stop new deliveries, drop queued events and stop running handlers, without waiting for the handler that called close.
+     * When queued events are dropped, one events.discarded Debug record reports how many, and
+     * diagnostics().counters.eventsDropped.closed counts them
+     *
+     * @remarks
+     * Stops the subscription when the Effect executes and interrupts its handlers
+     */
+    close(): Effect.Effect<void>
+    /**
+     * Wait until this subscription has closed and the SDK has released its queue and listeners.
+     * Normal closure succeeds with no value, and overflow fails with EventOverflowError, even for a later waiter.
+     * Cancelling this wait affects only the waiter, not the subscription or other waiters.
+     * Later waits see the same subscription outcome.
+     * Do not await this subscription's own closure from inside its handler
+     *
+     * @remarks
+     * Handlers or finalizers that disable interruption can delay completion.
+     * Unexpected faults remain in the Cause
+     */
+    waitForClose(): Effect.Effect<void, EventOverflowError>
+}
+
+/** Set event-handler queue limits, concurrency, ordering, overflow policy and an optional failure hook.
+ * Reporting uses the services available when the handler is registered.
+ * The type parameter T is the event payload that a partition function receives
+ *
+ * @category Events and collectors
+ */
+export interface EventHandlerOptions<E = never, R = never, T = unknown> extends HandlerOptions<T> {
+    /** Receive this subscription's failures instead of the client-level onError, with the original error and its full Cause
+     *
+     * A failure only queues its report, so the hook never holds a handler slot. One worker with the services available at
+     * registration delivers reports one at a time in order, with up to 64 waiting while the hook is busy. Later ones
+     * are logged instead, with fields.reportOutcome "queueFull", and counted in diagnostics().counters.reportsDropped.
+     * A failed or defective hook is logged together with the original failure and is never retried.
+     * Reports already queued when the subscription closes are still delivered. Client shutdown interrupts a running
+     * hook and waits at most one second for its cleanup, then logs the interrupted and queued reports at Error
+     * with fields.reportOutcome "interrupted" or "subscriptionClosed". A hook that interrupts itself also logs its report
+     * with "interrupted", and later reports still reach the hook
+     */
+    readonly onError?: (report: FailureReport) => Effect.Effect<unknown, E, R>
+}
+
+/**
+ * Event middleware for the Effect API, run around each client.on handler invocation that starts after registration.
+ * It receives the invocation and a next Effect that runs the rest of the chain and the handler.
+ * The next Effect completes when the rest of the chain has finished, whether or not it failed, and never fails.
+ * Failures after next are reported by the SDK where they occur, so middleware can time or trace a handler but cannot hide its failure.
+ * A failed or defective middleware Effect is reported like a handler failure, with its full Cause
+ *
+ * @category Events and collectors
+ */
+export type EventMiddleware<M extends MessageCore = Message, E = never, R = never> = (
+    invocation: EventInvocation<M>,
+    next: Effect.Effect<void>,
+) => Effect.Effect<unknown, E, R>
+
+/**
+ * Remove event middleware registered with client.use before its registration Scope closes
+ *
+ * @category Events and collectors
+ */
+export interface MiddlewareRegistration {
+    /** Stop applying the middleware to invocations that start later. Invocations already running keep their chain. Repeated calls do nothing */
+    close(): Effect.Effect<void>
+}
+
+export function nativeSubscription(source: Pick<EventSource, "stop" | "closed" | "id">): Subscription {
+    return Object.freeze({
+        id: source.id,
+        close: () => Effect.sync(() => source.stop()),
+        waitForClose: () => Deferred.await(source.closed),
+    })
+}

package/src/api/effect/failures.ts

@@ -0,0 +1,14 @@
+import type * as Cause from "effect/Cause"
+import type { FailureReport as SharedFailureReport } from "#sdk/failures"
+
+/**
+ * A failure outside any returned result, delivered to a native onError hook or logged at Error with its full error.
+ * The error field is the handler's typed failure or defect value, and cause keeps the complete Effect Cause, including every reason.
+ * The report holds IDs only, never message content
+ *
+ * @category Logging and diagnostics
+ */
+export interface FailureReport extends SharedFailureReport {
+    /** The complete Effect Cause of the failure */
+    readonly cause: Cause.Cause<unknown>
+}