@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/api/effect/stickers.ts

@@ -0,0 +1,112 @@
+import type {
+    GuildSticker,
+    ExpressionReference,
+    ExpressionMetadata,
+    ExpressionSourceGuild,
+    StickerCreate,
+    StickerEdit,
+    ExpressionBatch,
+    ExpressionDeleteOptions,
+} from "#sdk/expressions"
+import type * as Effect from "effect/Effect"
+import type { GuildOperationFailure, GuildOperationOptions, ModerationOptions } from "#sdk/guilds"
+
+/** Read, upload, edit, clone or delete custom stickers.
+ * 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 Stickers {
+    /**
+     * Replace a sticker's name, description and tags without changing its image or fetching it first.
+     * A fetched sticker can be spread into input if its identity matches the target.
+     * Unknown fields fail locally.
+     * An empty or null description clears it, and [] clears tags.
+     * The namespace's write, failure and cancellation rules apply
+     */
+    edit(
+        target: ExpressionReference,
+        input: StickerEdit,
+        options?: ModerationOptions,
+    ): Effect.Effect<GuildSticker, GuildOperationFailure>
+    /**
+     * Look up cached sticker 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<GuildSticker | undefined>
+    /**
+     * Fetch a community's sticker 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 GuildSticker[], GuildOperationFailure>
+    /**
+     * Fetch minimal sticker 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 sticker 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 sticker 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 sticker 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: StickerCreate,
+        options?: ModerationOptions,
+    ): Effect.Effect<GuildSticker, GuildOperationFailure>
+    /**
+     * Upload 1–50 community stickers 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 sticker 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 StickerCreate[],
+        options?: ModerationOptions,
+    ): Effect.Effect<ExpressionBatch<GuildSticker>, GuildOperationFailure>
+    /**
+     * Copy a sticker 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<GuildSticker, GuildOperationFailure>
+    /**
+     * Remove a sticker, 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/supervisor.ts

@@ -0,0 +1,58 @@
+import { makeNativeSupervisor } from "#sdk/native-supervisor"
+import { openClient } from "./client.js"
+
+/**
+ * Run bot workers in separate Node processes on this machine.
+ * The create method validates the process plan when executed but starts no children.
+ * The start method launches those children once and waits for their assignment and configuration acknowledgements, not gateway READY.
+ * The waitForReady method waits for a later all-child READY state without starting or stopping the supervisor.
+ * The waitForClose method waits until every owned child exits. Cancelling that wait does not stop the children.
+ * The status method returns a frozen snapshot of each child's latest reported gateway state for its current process generation.
+ * The snapshot is local, not a simultaneous health check across processes
+ *
+ * Each child module must execute supervisor.child.run, which owns a nested client and an inter-process communication (IPC) cleanup scope.
+ * The helper preserves the caller's Effect services and Cause. It asks the parent for a permit immediately before each fresh gateway Identify.
+ * Identify authenticates a new gateway session. Resuming an existing session needs no permit.
+ * Only one parent permit can be outstanding. The child confirms its synchronous Identify send or cancels before sending.
+ * The parent spaces fresh sends by at least one second, unless identify.coordinator paces them.
+ * A stalled child must stop and exit before another permit is issued, followed by a full spacing interval
+ *
+ * The supervisor can size the plan at start with totalShards "auto", share the Identify budget through identify.coordinator and
+ * include each child's client diagnostics in status. Children keep resumable sessions through clientOptions.sharding.sessions.
+ * The children share Fluxer's limits per bot account through the parent. When one child is rate-limited globally, the parent
+ * holds the other children's REST requests until the same time. Member requests from all children share one count of 12 in
+ * any 11 seconds, and a members.iterateChunks request past it fails at once with reason rateLimit and retryAfterMs.
+ * A child that gets no answer from the parent within one second counts only its own member requests and logs
+ * supervisor.memberRequestsLocal once. Per-route REST rate limits stay per child, and other processes using the same
+ * token are not counted.
+ * It installs no signal handlers and does not terminate the process.
+ * After the configured graceful deadline, the parent can terminate only its own unresponsive child and still waits for its exit.
+ * A crashed child restarts by default, up to three times in a row with exponentially increasing delays.
+ * Set restart to false to turn this off.
+ * The childEnvironment, args and execArgv options configure children but never appear in status or failures.
+ * Child output follows childOutput: Lines are forwarded with a child label by default, and inherit or ignore can be chosen instead
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { supervisor } from "@neontechspace/fluxerly/effect"
+ *
+ * export const workers = Effect.gen(function* () {
+ *     const managed = yield* supervisor.create({
+ *         entry: "/srv/bot-worker.js",
+ *         totalShards: 2,
+ *         assignments: [
+ *             { id: "one", shardIds: [0] },
+ *             { id: "two", shardIds: [1] },
+ *         ],
+ *     })
+ *     yield* managed.start().pipe(
+ *         Effect.andThen(managed.waitForClose()),
+ *         Effect.ensuring(managed.shutdown()),
+ *     )
+ *     return managed.status()
+ * })
+ * ```
+ *
+ * @category Sharding and supervision
+ */
+export const supervisor: import("#sdk/native-supervisor").NativeSupervisorTools = makeNativeSupervisor(openClient)

package/src/api/effect/threads.ts

@@ -0,0 +1,221 @@
+import type * as Effect from "effect/Effect"
+import type * as Stream from "effect/Stream"
+import type {
+    GuildThreadChannel,
+    ThreadMember,
+    ChannelOperationFailure,
+    ChannelOperationOptions,
+    ChannelAuditOperationOptions,
+} from "#sdk/channels"
+import type { Message, MessageCore, MessageReference } from "#sdk/messages"
+import type { PaginationError } from "#sdk/pagination"
+import type {
+    ArchivedThreadPage,
+    ArchivedThreadQuery,
+    ForumPost,
+    ForumPostCreate,
+    ThreadCreate,
+    ThreadEdit,
+    ThreadFromMessageCreate,
+    ThreadMemberIterationQuery,
+    ThreadMemberPageQuery,
+    ThreadMemberQuery,
+    ThreadSearchPage,
+    ThreadSearchQuery,
+} from "#sdk/threads"
+
+/** Create threads and forum posts, change, list and search threads, and manage thread members.
+ * HTTP methods return Effects and do not connect the gateway.
+ * Bots can use threads in every community where Fluxer enables them, without a capability setting.
+ * Read a thread with channels.fetch, delete it with channels.delete and send to it with messages.send and its ID
+ *
+ * Supply decimal IDs. Thread requests share this client's REST slots and queue limits with the other HTTP methods.
+ * Total deadline defaults to the client's rest.defaultTimeoutMs, 30,000 ms unless configured, including queue waits,
+ * retries and rate-limit waits. Reads retry transport failures and HTTP 500/502/503/504 at most twice.
+ * Writes retry only confirmed 429 responses, and no write is followed by an automatic confirmation fetch
+ *
+ * Manage Threads is an elevated permission.
+ * In a community whose mfaLevel is GuildMfaLevels.Elevated, an action that needs it fails with apiError.code twoFactorRequired, unless the bot owns the community or its application owner has two-factor authentication enabled.
+ * The create, createFromMessage, createPost and edit methods accept ChannelAuditOperationOptions, and the other methods
+ * reject auditReason. The fetchActive list enters the enabled channel cache, while archived pages, search results,
+ * forum posts and member reads do not. The edit, join, leave, addMember and removeMember methods remove their thread
+ * from the enabled channel cache
+ *
+ * Operation inputs are copied when the Effect executes. Expected failures use ChannelOperationError, whose operation
+ * names the threads method, or ClientClosedError. Interruption and defects retain Cause after owned cleanup
+ *
+ * @category Channels
+ */
+export interface Threads<M extends MessageCore = Message> {
+    /**
+     * Create a thread that is not attached to a message in a text or announcement channel, and return its frozen
+     * snapshot. The bot becomes the thread's first member, and Fluxer posts a ThreadCreated notice in the parent channel
+     * for a public or announcement thread.
+     * Fluxer requires Create Public Threads, or Create Private Threads for a private thread.
+     * Use createPost in a forum or media channel.
+     * A lost response can leave the thread created, and the SDK never resends it
+     *
+     * @example
+     * ```ts
+     * import { Effect } from "effect"
+     * import { ChannelType, ThreadAutoArchiveMinutes, type Client } from "@neontechspace/fluxerly/effect"
+     * export const threadExample = (client: Client, channelId: string) =>
+     *     client.threads
+     *         .create(channelId, {
+     *             name: "Release planning",
+     *             type: ChannelType.PrivateThread,
+     *             autoArchiveMinutes: ThreadAutoArchiveMinutes.OneDay,
+     *         })
+     *         .pipe(Effect.flatMap((thread) => client.messages.send(thread.id, "Planning starts here")))
+     * ```
+     */
+    create(
+        channelId: string,
+        input: ThreadCreate,
+        options?: ChannelAuditOperationOptions,
+    ): Effect.Effect<GuildThreadChannel, ChannelOperationFailure>
+    /**
+     * Start a public thread on an existing message and return its frozen snapshot.
+     * The thread takes the message's ID, and the message gains MessageFlags.HasThread.
+     * Only a default message or a reply in a text or announcement channel can start a thread, and only one.
+     * In an announcement channel the thread is an announcement thread.
+     * Fluxer posts a ThreadCreated notice in the parent channel unless the message is among its five newest messages.
+     * Fluxer requires Create Public Threads and Read Message History.
+     * A lost response can leave the thread created, and the SDK never resends it.
+     * After an unknown outcome, channels.fetch(message.id) shows whether the thread exists
+     */
+    createFromMessage(
+        message: MessageReference,
+        input: ThreadFromMessageCreate,
+        options?: ChannelAuditOperationOptions,
+    ): Effect.Effect<GuildThreadChannel, ChannelOperationFailure>
+    /**
+     * Create a post in a forum or media channel, a public thread with its first message, and return both frozen.
+     * Files in the message are sent inline as multipart form data in the same request, never through presigned uploads,
+     * under messages.send's attachment rules and the client's upload budget.
+     * Fluxer requires Send Messages in the channel plus the permissions the message content needs, and applies the
+     * channel's tag rules. When the first message fails, Fluxer removes the new post again.
+     * A lost response can leave the post created, and the SDK never resends it
+     */
+    createPost(
+        channelId: string,
+        input: ForumPostCreate,
+        options?: ChannelAuditOperationOptions,
+    ): Effect.Effect<ForumPost<M>, ChannelOperationFailure>
+    /**
+     * Change only the supplied thread settings and return the frozen thread.
+     * It uses the route and rate limit of channels.edit. ThreadEdit describes which changes the thread's creator may
+     * make and which need Manage Threads
+     */
+    edit(
+        threadId: string,
+        input: ThreadEdit,
+        options?: ChannelAuditOperationOptions,
+    ): Effect.Effect<GuildThreadChannel, ChannelOperationFailure>
+    /**
+     * Fetch every active thread the bot can view in a community, newest first, as one frozen list.
+     * A private thread appears when the bot joined it or can manage threads in its parent channel.
+     * Each thread the bot joined has membership set
+     */
+    fetchActive(
+        guildId: string,
+        options?: ChannelOperationOptions,
+    ): Effect.Effect<readonly GuildThreadChannel[], ChannelOperationFailure>
+    /**
+     * Fetch one frozen page of archived threads of a text, announcement, forum or media channel, as ArchivedThreadQuery
+     * selects. Scopes "public" and "private" list the most recently archived first, and "joinedPrivate" lists the newest
+     * threads first. Each thread the bot joined has membership set.
+     * Fluxer requires Read Message History, plus Manage Threads for scope "private"
+     */
+    fetchArchived(
+        channelId: string,
+        query?: ArchivedThreadQuery,
+        options?: ChannelOperationOptions,
+    ): Effect.Effect<ArchivedThreadPage, ChannelOperationFailure>
+    /**
+     * Search the threads of a text, announcement, forum or media channel by name, tags and state, and return one frozen
+     * page. Fluxer requires Read Message History.
+     * While Fluxer builds the community's search index it answers HTTP 202 with code SEARCH_INDEX_NOT_READY, which this
+     * method returns as an indexing page without retrying. Any other HTTP 202 answer fails with reason response.
+     * While Fluxer's search service is turned off, the call fails with reason rejected and apiError.providerCode
+     * FEATURE_TEMPORARILY_DISABLED
+     */
+    search(
+        channelId: string,
+        query?: ThreadSearchQuery,
+        options?: ChannelOperationOptions,
+    ): Effect.Effect<ThreadSearchPage<M>, ChannelOperationFailure>
+    /**
+     * Add the bot to a thread, succeeding with no value after HTTP 204. Joining a thread the bot already belongs to also
+     * succeeds. An archived thread cannot be joined, and a locked one needs Manage Threads
+     */
+    join(threadId: string, options?: ChannelOperationOptions): Effect.Effect<void, ChannelOperationFailure>
+    /**
+     * Remove the bot from a thread, succeeding with no value after HTTP 204.
+     * An archived thread cannot be left, and Fluxer rejects a bot that is not a member with UNKNOWN_THREAD_MEMBER
+     */
+    leave(threadId: string, options?: ChannelOperationOptions): Effect.Effect<void, ChannelOperationFailure>
+    /**
+     * Add a community member who can view the parent channel to a thread, succeeding with no value after HTTP 204.
+     * Adding a current member also succeeds, and otherwise Fluxer posts a RecipientAdd notice in the thread.
+     * Fluxer requires Send Messages In Threads, plus Manage Threads in a locked thread and in a private thread that is
+     * not invitable, unless the added member can manage threads. An archived thread accepts no new members
+     */
+    addMember(
+        threadId: string,
+        userId: string,
+        options?: ChannelOperationOptions,
+    ): Effect.Effect<void, ChannelOperationFailure>
+    /**
+     * Remove a member from a thread, succeeding with no value after HTTP 204, and Fluxer posts a RecipientRemove notice
+     * in the thread. Removing the bot's own ID works like leave.
+     * Fluxer requires Manage Threads unless the bot created the private thread. A user who is not a member fails with
+     * UNKNOWN_THREAD_MEMBER, and an archived thread cannot change
+     */
+    removeMember(
+        threadId: string,
+        userId: string,
+        options?: ChannelOperationOptions,
+    ): Effect.Effect<void, ChannelOperationFailure>
+    /**
+     * Fetch one thread member as a frozen ThreadMember. A user who is not a member fails with UNKNOWN_THREAD_MEMBER.
+     * With withMember, member holds the user's community membership while the user has one. Its community comes from
+     * the channel cache when the thread is cached there, otherwise from one extra channel read that shares the deadline
+     * and whose failure fails this call
+     */
+    fetchMember(
+        threadId: string,
+        userId: string,
+        query?: ThreadMemberQuery,
+        options?: ChannelOperationOptions,
+    ): Effect.Effect<ThreadMember, ChannelOperationFailure>
+    /**
+     * Fetch one page of thread members in ascending user ID order, as frozen ThreadMember values.
+     * With withMember, each member holds the user's community membership while the user has one, with the community
+     * resolved as fetchMember describes
+     */
+    fetchMembers(
+        threadId: string,
+        query?: ThreadMemberPageQuery,
+        options?: ChannelOperationOptions,
+    ): Effect.Effect<readonly ThreadMember[], ChannelOperationFailure>
+    /**
+     * Read thread members in ascending user ID order, buffering one page and never prefetching.
+     * The maxItems option is required. The pageSize option defaults to 100 and accepts 1–100, maxPages defaults to 100,
+     * and timeoutMs applies to each page. An empty page or maxItems ends the scan.
+     * Invalid traversal input, a stalled cursor or reaching the page budget fails with PaginationError, and remote
+     * failures keep threads.fetchMembers's errors.
+     * With withMember, one consumption resolves the thread's community once, as fetchMember describes.
+     * Each consumption is independent, and client closure releases the page and fails the next pull
+     *
+     * @remarks
+     * The returned Stream reads pages only while it is consumed.
+     * Failures end the Stream in its error channel.
+     * Interruption waits for request cleanup, and ending consumption releases the buffered page
+     */
+    iterateMembers(
+        threadId: string,
+        query: ThreadMemberIterationQuery,
+        options?: ChannelOperationOptions,
+    ): Stream.Stream<ThreadMember, ChannelOperationFailure | PaginationError>
+}

package/src/api/effect/users.ts

@@ -0,0 +1,66 @@
+import type { User, UserProfile, UserProfileQuery, UserOperationFailure, UserOperationOptions } from "#sdk/users"
+import type * as Effect from "effect/Effect"
+
+/** Read public account information or a privacy-filtered profile.
+ * 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 Users {
+    /**
+     * Look up a public account 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<User | undefined>
+    /**
+     * Look up the bot's own public account as the gateway's READY reported it, without a request.
+     * The result is undefined until this client's first READY, and also while no READY has carried a complete public account.
+     * A later READY with a complete public account, such as for a new session, replaces it, while an incomplete one keeps the previous account.
+     * Other user updates and fetchSelf results do not change it, so its username or avatar can be stale.
+     * The value remains available after the client stops.
+     * This lookup never fails. Use fetchSelf for a current remote snapshot
+     */
+    getSelf(): Effect.Effect<User | undefined>
+    /**
+     * Fetch a public account snapshot by decimal user ID.
+     * An unknown user fails with reason notFound rather than an empty result.
+     * With the user cache enabled, a concurrent fetch of another user ID does not keep this result from being stored, unless more than 256 user IDs are being read at once
+     */
+    fetch(id: string, options?: UserOperationOptions): Effect.Effect<User, UserOperationFailure>
+    /**
+     * Fetch a user's privacy-filtered profile, optionally for the community specified in query.guildId.
+     * The frozen result includes only documented identity and profile fields.
+     * The isLimited field reports Fluxer's privacy restriction, not missing community membership.
+     * A guildProfile of null means no contextual profile was supplied, not proof the user is outside the community.
+     * No gateway connection, hidden member fetch or account or profile cache use is performed, and each call issues a separate read.
+     * Users' shared deadlines and eligible read retries apply.
+     * Fluxer may clear expired premium state while serving this GET.
+     * Invalid input, denied access or a malformed response fails with UserOperationError for users.fetchProfile.
+     * Cancellation affects this request only and waits for cleanup
+     *
+     * @example
+     * ```ts
+     * import type { Client } from "@neontechspace/fluxerly/effect"
+     * export function profileExample(client: Client, userId: string, guildId: string) {
+     *     return client.users.fetchProfile(userId, { guildId })
+     * }
+     * ```
+     */
+    fetchProfile(
+        id: string,
+        query?: UserProfileQuery,
+        options?: UserOperationOptions,
+    ): Effect.Effect<UserProfile, UserOperationFailure>
+    /**
+     * Fetch the authenticated bot's public account data remotely.
+     * Private account fields are excluded.
+     * With the user cache enabled, the bot's ID is unknown until the response arrives, so some concurrent user cache changes keep the result out of the cache.
+     * Examples are another users.fetch or users.fetchSelf call, a user update event and a lost gateway connection
+     */
+    fetchSelf(options?: UserOperationOptions): Effect.Effect<User, UserOperationFailure>
+}

package/src/api/effect/webhook-client.ts

@@ -0,0 +1,206 @@
+import {
+    type IncomingWebhook,
+    type WebhookTokenEdit,
+    type WebhookMessageInput,
+    type WebhookMessageEdit,
+    type WebhookClientOptions,
+    type WebhookOperationFailure,
+    type WebhookMessageOperationOptions,
+} from "#sdk/webhooks"
+import {
+    makeWebhookClient,
+    webhookTokenFetch,
+    webhookTokenEdit,
+    webhookTokenDelete,
+    webhookSend,
+    webhookMessageFetch,
+    webhookMessageEdit,
+    webhookMessageDelete,
+} from "#sdk/internal/webhooks"
+import * as Effect from "effect/Effect"
+import * as Scope from "effect/Scope"
+import type { InstanceResolveOptions } from "#sdk/instance"
+import type { Message, MessageOperationOptions } from "#sdk/messages"
+import { type ResolvedInstance, effectInstance, type Instance } from "./instance.js"
+
+/** Send and manage one incoming webhook's messages using its webhook token.
+ * Follower webhooks have no exposed token and Fluxer rejects their token-authenticated operations with UNKNOWN_WEBHOOK.
+ * This client does not use a bot token, connect the gateway, cache resources or store tokens persistently
+ *
+ * Operations start when executed and preserve unexpected faults/interruption.
+ * Cleanup defects stop retries and preserve any operation failure or interruption alongside the defect in Cause
+ *
+ * Requests default to a 30-second total deadline across queue waits, rate-limit waits, retries and HTTP.
+ * Confirmed HTTP 429 responses use this client's shared rate-limit state as described on Client.
+ * Cancellation interrupts only that operation and awaits request/body cleanup, without rolling back remote effects
+ *
+ * Errors contain only safe categories and status, never credential-bearing paths or upstream bodies
+ *
+ * Successful JSON bodies are capped at 16 MiB of response-body bytes before parsing, not total heap usage. Oversized successes fail with reason response.
+ * A response failure after a mutation request was sent leaves an unknown outcome and never retries automatically
+ *
+ * Other client caches are not updated by this token-only client
+ *
+ * @category Invites and webhooks
+ */
+export interface WebhookClient {
+    /**
+     * The webhook's decimal ID, without its token or a token-bearing URL
+     */
+    readonly id: string
+    /**
+     * Resolve this webhook client's selected instance and get pure URL helpers for it
+     */
+    readonly instance: Instance
+    /**
+     * Fetch this incoming webhook's current metadata using its token, not bot authentication.
+     * Creator and private fields are not retained
+     */
+    fetch(options?: MessageOperationOptions): Effect.Effect<IncomingWebhook, WebhookOperationFailure>
+    /**
+     * Change this webhook's name or avatar using its token and return metadata without credentials.
+     * To move it to another channel, use a bot client's webhooks.edit.
+     * A failed or cancelled write can still have applied.
+     * This method does not close the client
+     */
+    edit(
+        input: WebhookTokenEdit,
+        options?: MessageOperationOptions,
+    ): Effect.Effect<IncomingWebhook, WebhookOperationFailure>
+    /**
+     * Delete this webhook remotely using its token, succeeding after HTTP 204.
+     * This does not close the client or release its local credential reference.
+     * Later requests normally fail with notFound because the token was revoked.
+     * Call shutdown separately to release the client's local resources
+     */
+    delete(options?: MessageOperationOptions): Effect.Effect<void, WebhookOperationFailure>
+    /**
+     * Send a webhook message and return the created message after Fluxer's HTTP response.
+     * A plain string sends only that text, as shorthand for `{ content }`.
+     * The SDK uses wait=true, and mentions are disabled by default.
+     * A supplied nonce requests best-effort duplicate suppression for five minutes, not exactly-once delivery.
+     * Without a nonce, none is sent unless a forward source supplies one, and a nonce on both the message and its forward source fails before dispatch.
+     * Reply references can include files.
+     * Forward references preserve only the source snapshot and reject new content or uploads
+     *
+     * Set threadId to post into an existing thread. In a forum or media channel, set threadName, with optional
+     * appliedTagIds, to start a new post instead. The result is then the post's first message, whose channelId is the
+     * new post's ID. See WebhookMessageInput for the rules that the SDK checks before dispatch
+     *
+     * Each attachment supplies data bytes, a sized Blob or File source, or a finite stream with its exact size.
+     * Metadata and data bytes are copied when execution starts, before waiting.
+     * File and stream sources are read when the multipart upload begins, without copying or spooling.
+     * Keep file data stable, and supply a fresh stream for each operation because a stream is consumed at most once and must deliver exactly its declared size.
+     * Cleanup cancels unfinished readers and awaits lock release, without closing caller paths or FileHandles.
+     * Multipart file uploads are streamed with a maximum of 50 MiB per file and share the configured upload-byte budget.
+     * An attachment:// image or thumbnail URL must match one new upload whose filename maps to an image or video MIME type.
+     * The flags input accepts only MessageFlags.SuppressEmbeds and MessageFlags.SuppressNotifications.
+     * Crossposted, IsCrosspost and SourceMessageDeleted are server-managed.
+     * Those bits and VoiceMessage fail locally before dispatch
+     *
+     * A failure with an unknown outcome can leave the message posted and is never replayed automatically.
+     * A confirmed inline HTTP 429 can replay copied data bytes, but file and stream inputs fail with rateLimit without being reopened or reread
+     */
+    send(
+        input: WebhookMessageInput | string,
+        options?: MessageOperationOptions,
+    ): Effect.Effect<Message, WebhookOperationFailure>
+    /**
+     * Fetch a message authored by this webhook in its current channel, using a decimal message ID.
+     * For a message in a thread, including a forum post, set options.threadId to the thread's ID.
+     * Eligible transient read failures have bounded retries
+     */
+    fetchMessage(
+        messageId: string,
+        options?: WebhookMessageOperationOptions,
+    ): Effect.Effect<Message, WebhookOperationFailure>
+    /**
+     * Change this webhook's message and return its updated snapshot.
+     * A plain string replaces only the text, as shorthand for `{ content }`.
+     * Omitted fields stay unchanged.
+     * Mentions default off and attachments cannot be replaced.
+     * A flags-only edit replaces only MessageFlags.SuppressEmbeds and MessageFlags.SuppressNotifications, and 0 clears them.
+     * Crossposted, IsCrosspost and SourceMessageDeleted are server-managed.
+     * Those bits and VoiceMessage fail locally before dispatch.
+     * Embed input cannot resolve existing file references.
+     * For a message in a thread, including a forum post, set options.threadId to the thread's ID
+     */
+    editMessage(
+        messageId: string,
+        input: WebhookMessageEdit | string,
+        options?: WebhookMessageOperationOptions,
+    ): Effect.Effect<Message, WebhookOperationFailure>
+    /**
+     * Delete this webhook's message, succeeding with no value after HTTP 204.
+     * For a message in a thread, including a forum post, set options.threadId to the thread's ID.
+     * Success does not prove the message previously existed.
+     * A failure with an unknown outcome can leave the message deleted
+     */
+    deleteMessage(
+        messageId: string,
+        options?: WebhookMessageOperationOptions,
+    ): Effect.Effect<void, WebhookOperationFailure>
+    /**
+     * Permanently stop this local client, reject new work, cancel active work and await transport cleanup.
+     * The client's token reference is released, but the remote webhook and caller-held credentials remain.
+     * Concurrent calls wait for the same pending cleanup.
+     * No expected failure is returned
+     *
+     * @remarks
+     * Cleanup defects remain in the Cause
+     */
+    shutdown(): Effect.Effect<void>
+}
+
+/**
+ * Create a webhook-only client for hosted Fluxer or an explicitly selected self-hosted instance, from { id, token } or redacted creation credentials.
+ * Validate the inputs locally without requests. The client copies the credential into its own redacted reference.
+ * Creation starts when the Effect executes. Closing its Scope shuts down the client.
+ * The Effect Clock available when creation executes owns this client's request queue and deadlines. Providing a
+ * different Clock around a later operation does not replace that owner Clock.
+ * The SDK does not persist the token, connect a gateway or authenticate as a bot. Reuse one client per credential to share request slots, queue limits and rate-limit waits.
+ * Invalid configuration is misuse and dies with ConfigurationError, and other defects retain their Cause
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { createWebhookClient } from "@neontechspace/fluxerly/effect"
+ * export const webhookExample = (id: string, token: string) => Effect.scoped(Effect.gen(function* () {
+ *     const webhook = yield* createWebhookClient({ id, token })
+ *     const message = yield* webhook.send({ content: "Deploying…" })
+ *     return yield* webhook.editMessage(message.id, { content: "Deployed" })
+ * }))
+ * ```
+ *
+ * @category Invites and webhooks
+ */
+export function createWebhookClient(options: WebhookClientOptions): Effect.Effect<WebhookClient, never, Scope.Scope> {
+    return Effect.gen(function* () {
+        const owner = yield* makeWebhookClient(options, true).pipe(Effect.orDie)
+        yield* Effect.addFinalizer(() => owner.shutdown())
+        let instance: ResolvedInstance | undefined
+        return Object.freeze({
+            id: owner.id,
+            instance: Object.freeze({
+                resolve: (options?: InstanceResolveOptions) =>
+                    owner.instance
+                        .resolveInfo(options)
+                        .pipe(Effect.map((value) => (instance ??= effectInstance(value)))),
+            }),
+            fetch: (options?: MessageOperationOptions) =>
+                owner.run("webhooks.fetchToken", () => webhookTokenFetch(owner.id), options),
+            edit: (input: WebhookTokenEdit, options?: MessageOperationOptions) =>
+                owner.run("webhooks.editToken", () => webhookTokenEdit(owner.id, input), options),
+            delete: (options?: MessageOperationOptions) =>
+                owner.run("webhooks.deleteToken", () => webhookTokenDelete(owner.id), options),
+            send: (input: WebhookMessageInput | string, options?: MessageOperationOptions) =>
+                owner.run("webhooks.send", () => webhookSend(owner.id, input), options),
+            fetchMessage: (id: string, options?: WebhookMessageOperationOptions) =>
+                owner.run("webhooks.fetchMessage", () => webhookMessageFetch(owner.id, id, options), options),
+            editMessage: (id: string, input: WebhookMessageEdit | string, options?: WebhookMessageOperationOptions) =>
+                owner.run("webhooks.editMessage", () => webhookMessageEdit(owner.id, id, input, options), options),
+            deleteMessage: (id: string, options?: WebhookMessageOperationOptions) =>
+                owner.run("webhooks.deleteMessage", () => webhookMessageDelete(owner.id, id, options), options),
+            shutdown: () => owner.shutdown(),
+        })
+    })
+}