@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/api/default/stickers.ts

@@ -0,0 +1,129 @@
+import type {
+    GuildSticker,
+    ExpressionReference,
+    ExpressionMetadata,
+    ExpressionSourceGuild,
+    StickerCreate,
+    StickerEdit,
+    ExpressionBatch,
+    DefaultExpressionDeleteOptions,
+} from "#sdk/expressions"
+import type { ResultAsync } from "neverthrow"
+import type { GuildOperationFailure, DefaultGuildOperationOptions, DefaultModerationOptions } from "#sdk/guilds"
+import type { CancelledError, ConfigurationError } from "#sdk/errors"
+
+/**
+ * Create, list, copy, edit and delete community stickers.
+ * Use get for an optional local cache lookup, or fetchAll, fetchMetadata and fetchSource for remote reads.
+ * Shared guild request limits, deadlines and read retries apply.
+ * Writes retry only confirmed HTTP 429 rejections.
+ * Input, permission, not-found and malformed-response errors are not retried.
+ * A lost response can leave a write applied.
+ * Results are frozen snapshots, not gateway acknowledgement
+ *
+ * Expected failures return GuildOperationError or ClientClosedError.
+ * Abort returns CancelledError after cleanup.
+ * Unexpected failures reject with SdkDefect
+ *
+ * @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?: DefaultModerationOptions,
+    ): ResultAsync<GuildSticker, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * 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
+     *
+     * @remarks
+     * Returns the value synchronously.
+     * Unexpected failures throw SdkDefect
+     */
+    get(target: ExpressionReference): 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?: DefaultGuildOperationOptions,
+    ): ResultAsync<readonly GuildSticker[], GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Fetch minimal sticker metadata by decimal ID, without requiring source-community membership.
+     * This read does not populate the cache
+     */
+    fetchMetadata(
+        id: string,
+        options?: DefaultGuildOperationOptions,
+    ): ResultAsync<ExpressionMetadata, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * 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?: DefaultGuildOperationOptions,
+    ): ResultAsync<ExpressionSourceGuild, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * 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?: DefaultModerationOptions,
+    ): ResultAsync<GuildSticker, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * 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?: DefaultModerationOptions,
+    ): ResultAsync<ExpressionBatch<GuildSticker>, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * 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?: DefaultModerationOptions,
+    ): ResultAsync<GuildSticker, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * 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?: DefaultExpressionDeleteOptions,
+    ): ResultAsync<void, GuildOperationFailure | CancelledError | ConfigurationError>
+}

package/src/api/default/supervisor.ts

@@ -0,0 +1,53 @@
+import { makeDefaultSupervisor } from "#sdk/default-supervisor"
+import { createClient } from "./client.js"
+
+/**
+ * Run a fixed group of local Node.js child processes, each with its own client and assigned shards.
+ * Use create to validate the assignments, then start to launch the children.
+ * Each child entry module must call supervisor.child.run to create and run its client
+ *
+ * @remarks
+ * The start method waits for assignment and configuration acknowledgements, not gateway READY.
+ * Use waitForReady for all-child READY, and waitForClose to wait until this supervisor's children have exited.
+ * The status method returns a frozen local report with the latest gateway state received from each current child.
+ * Those states are separate observations, not an atomic health check across processes
+ *
+ * Fresh gateway Identify sends require a parent permit and are spaced by at least one second, unless identify.coordinator paces them.
+ * Identify authenticates a new session, while Resume reuses an earlier gateway session.
+ * Session Resume sends do not need a permit.
+ * A permit stays outstanding until the child confirms the send or cancels before sending.
+ * A stalled child is stopped and must exit before another permit is issued, after a full spacing interval.
+ * The child helper receives a stop signal.
+ * A parent stop does not wait for an uncooperative configure promise or start its client afterward
+ *
+ * The parent can forcibly terminate only children it started after the graceful deadline, and still waits for their exit.
+ * No process signal handlers are installed.
+ * Child output follows childOutput: Lines are forwarded with a child label by default, and inherit or ignore can be chosen instead.
+ * 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 affect child launch but are omitted from status and failures.
+ * With totalShards "auto" and processes or shardsPerProcess, the plan is sized at start. Each child sends its client diagnostics, which status includes.
+ * 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
+ *
+ * @example
+ * ```ts
+ * import { supervisor } from "@neontechspace/fluxerly"
+ *
+ * export const workers = supervisor.create({
+ *     entry: "/srv/bot-worker.js",
+ *     totalShards: 2,
+ *     assignments: [
+ *         { id: "one", shardIds: [0] },
+ *         { id: "two", shardIds: [1] },
+ *     ],
+ * })
+ * ```
+ *
+ * @category Sharding and supervision
+ */
+export const supervisor: import("#sdk/default-supervisor").DefaultSupervisorTools = makeDefaultSupervisor(createClient)

package/src/api/default/threads.ts

@@ -0,0 +1,233 @@
+import type { ResultAsync, Result } from "neverthrow"
+import type {
+    GuildThreadChannel,
+    ThreadMember,
+    ChannelOperationFailure,
+    DefaultChannelOperationOptions,
+    DefaultChannelAuditOperationOptions,
+} from "#sdk/channels"
+import type { CancelledError, ConfigurationError } from "#sdk/errors"
+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.
+ * Every method uses HTTP without a gateway connection and starts immediately.
+ * 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
+ *
+ * @remarks
+ * Supply decimal IDs. Requests share the client's REST slots and queue limits.
+ * The default deadline, rest.defaultTimeoutMs (30,000 ms unless configured), includes capacity, rate-limit and retry waits.
+ * Eligible reads retry transport and HTTP 500, 502, 503 or 504 failures at most twice.
+ * Writes retry only confirmed HTTP 429 rejection, 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 a raw audit reason through
+ * DefaultChannelAuditOperationOptions, 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.
+ * Inputs are copied when called.
+ * Expected failures return ChannelOperationError, whose operation names the threads method, or ClientClosedError.
+ * Abort returns CancelledError after cleanup.
+ * Unexpected failures reject with SdkDefect
+ *
+ * @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 { ChannelType, ThreadAutoArchiveMinutes, type Client } from "@neontechspace/fluxerly"
+     * export async function threadExample(client: Client, channelId: string) {
+     *     const thread = await client.threads.create(channelId, {
+     *         name: "Release planning",
+     *         type: ChannelType.PrivateThread,
+     *         autoArchiveMinutes: ThreadAutoArchiveMinutes.OneDay,
+     *     })
+     *     if (thread.isErr()) throw thread.error
+     *     return client.messages.send(thread.value.id, "Planning starts here")
+     * }
+     * ```
+     */
+    create(
+        channelId: string,
+        input: ThreadCreate,
+        options?: DefaultChannelAuditOperationOptions,
+    ): ResultAsync<GuildThreadChannel, ChannelOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * 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?: DefaultChannelAuditOperationOptions,
+    ): ResultAsync<GuildThreadChannel, ChannelOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * 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?: DefaultChannelAuditOperationOptions,
+    ): ResultAsync<ForumPost<M>, ChannelOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * 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?: DefaultChannelAuditOperationOptions,
+    ): ResultAsync<GuildThreadChannel, ChannelOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * 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?: DefaultChannelOperationOptions,
+    ): ResultAsync<readonly GuildThreadChannel[], ChannelOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * 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?: DefaultChannelOperationOptions,
+    ): ResultAsync<ArchivedThreadPage, ChannelOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * 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?: DefaultChannelOperationOptions,
+    ): ResultAsync<ThreadSearchPage<M>, ChannelOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * 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?: DefaultChannelOperationOptions,
+    ): ResultAsync<void, ChannelOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * 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?: DefaultChannelOperationOptions,
+    ): ResultAsync<void, ChannelOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * 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?: DefaultChannelOperationOptions,
+    ): ResultAsync<void, ChannelOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * 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?: DefaultChannelOperationOptions,
+    ): ResultAsync<void, ChannelOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * 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?: DefaultChannelOperationOptions,
+    ): ResultAsync<ThreadMember, ChannelOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * 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?: DefaultChannelOperationOptions,
+    ): ResultAsync<readonly ThreadMember[], ChannelOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * 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
+     * Consume the iterable with a for await loop, which starts the first request.
+     * An expected failure yields one Err and ends iteration.
+     * Breaking the loop releases the buffered page.
+     * Abort interrupts pending request work and waits for cleanup
+     */
+    iterateMembers(
+        threadId: string,
+        query: ThreadMemberIterationQuery,
+        options?: DefaultChannelOperationOptions,
+    ): AsyncIterable<
+        Result<ThreadMember, ChannelOperationFailure | PaginationError | CancelledError | ConfigurationError>
+    >
+}

package/src/api/default/users.ts

@@ -0,0 +1,82 @@
+import type { User, UserProfile, UserProfileQuery, UserOperationFailure, DefaultUserOperationOptions } from "#sdk/users"
+import type { ResultAsync } from "neverthrow"
+import type { CancelledError, ConfigurationError } from "#sdk/errors"
+
+/**
+ * Read public user account and profile data, without connecting the gateway.
+ * Use get for an explicitly enabled local account cache, or fetch for a remote read.
+ * HTTP calls start immediately with the client's default deadline (rest.defaultTimeoutMs, 30,000 ms unless configured) and bounded eligible read retries.
+ * Any writes retry only confirmed rate-limit rejection, not an uncertain outcome.
+ * Abort waits for cleanup and returns CancelledError.
+ * Unexpected failures reject with SdkDefect
+ *
+ * @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
+     *
+     * @remarks
+     * Returns the value synchronously.
+     * Unexpected failures throw SdkDefect
+     */
+    get(id: string): 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
+     *
+     * @remarks
+     * Returns the value synchronously
+     */
+    getSelf(): 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?: DefaultUserOperationOptions,
+    ): ResultAsync<User, UserOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * 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"
+     * export function profileExample(client: Client, userId: string, guildId: string) {
+     *     return client.users.fetchProfile(userId, { guildId })
+     * }
+     * ```
+     */
+    fetchProfile(
+        id: string,
+        query?: UserProfileQuery,
+        options?: DefaultUserOperationOptions,
+    ): ResultAsync<UserProfile, UserOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * 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?: DefaultUserOperationOptions,
+    ): ResultAsync<User, UserOperationFailure | CancelledError | ConfigurationError>
+}