@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/api/default/oauth.ts

@@ -0,0 +1,293 @@
+import type { GuildListQuery, GuildListSummary } from "#sdk/guilds"
+import * as Effect from "effect/Effect"
+import * as Exit from "effect/Exit"
+import * as Scope from "effect/Scope"
+import { ok, ResultAsync } from "neverthrow"
+import { causeReasons, suspendInput } from "#sdk/internal/defects"
+import {
+    createPkce,
+    type OAuthPkce,
+    type OAuthAuthorizationInput,
+    type OAuthConnection,
+    type OAuthCodeExchangeInput,
+    type OAuthConfig,
+    type OAuthIdentity,
+    type OAuthIntrospection,
+    type OAuthOperationFailure,
+    type OAuthTokens,
+    type DefaultOAuthOperationOptions,
+} from "#sdk/oauth"
+import { makeOAuthOwner } from "#sdk/internal/oauth"
+import { CancelledError, ConfigurationError, SdkDefect } from "#sdk/errors"
+import { executeOperation, fromExit } from "#sdk/internal/binding/execute"
+
+function oauthOwnerOptions(options: DefaultOAuthOperationOptions | undefined) {
+    if (Array.isArray(options)) return options
+    if (typeof options !== "object" || options === null || !("signal" in options)) return options
+    const { signal: _signal, ...ownerOptions } = options
+    return ownerOptions
+}
+
+/**
+ * Use a standalone OAuth client to exchange authorization codes, refresh or revoke tokens, and read delegated user data.
+ * This confidential client requires a server-held client secret, not a bot token.
+ * It does not open a browser, handle callbacks, compare state, store tokens or run a gateway.
+ * The application owns those steps and coordinates refreshes
+ *
+ * @remarks
+ * The secret is copied until shutdown.
+ * Calls start immediately and return ResultAsync.
+ * At most eight operations run at once.
+ * While eight are running, another operation fails at once with OAuthOperationError reason busy instead of waiting.
+ * The timeoutMs option defaults to 30,000 for discovery and the operation, with request cleanup awaited afterward.
+ * Responses are capped at 1 MiB and requests are never retried automatically.
+ * Discovery throttling returns OAuthOperationError with reason rateLimit, outcome notDispatched, status 429 and the server's retryAfterMs when available
+ *
+ * Expected failures return Err.
+ * A throw while reading input or option properties rejects with SdkDefect code application.defect and the thrown value
+ * as its cause, and unexpected cleanup failures reject with SdkDefect.
+ * It keeps the original cleanup failure, never response text, and its message and toJSON mask credential patterns
+ *
+ * @category OAuth
+ */
+export interface OAuthClient extends AsyncDisposable {
+    /**
+     * Build an authorization URL for the selected instance using its discovered web application URL, including its path.
+     * Supply the redirect URI, scopes, caller-generated state and S256 PKCE challenge, which binds the callback code to the private verifier.
+     * The application must retain state correlation and the PKCE verifier.
+     * Bot community and permission parameters are consent hints, not proof of installation or authorization.
+     * This returns the URL without opening it.
+     * Network failures retain only sanitized transport facts in cause
+     */
+    authorizationUrl(
+        input: OAuthAuthorizationInput,
+        options?: DefaultOAuthOperationOptions,
+    ): ResultAsync<string, OAuthOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Exchange the code from an authorization callback for access and refresh tokens.
+     * Supply the matching redirect URI and PKCE verifier.
+     * The application must store the returned tokens.
+     * After dispatch, cancellation or a lost response cannot tell whether Fluxer consumed the one-use code.
+     * Do not retry that exchange when its outcome is unknown.
+     * Network failures retain only sanitized transport facts in cause
+     */
+    exchangeCode(
+        input: OAuthCodeExchangeInput,
+        options?: DefaultOAuthOperationOptions,
+    ): ResultAsync<OAuthTokens, OAuthOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Exchange a refresh token for a new access and refresh token pair.
+     * Form tokens must contain 1–256 well-formed UTF-16 units without surrounding whitespace, U+000C or U+202E.
+     * Invalid values fail locally rather than being normalized, and this also applies to revoke and introspect tokens.
+     * Fluxer rotates refresh tokens.
+     * The application must coordinate refreshes and atomically replace both stored tokens after success, so it never stores a mixed pair.
+     * A refresh with an unknown outcome must not be retried, because it may have rotated the token.
+     * Network failures retain only sanitized transport facts in cause
+     */
+    refresh(
+        refreshToken: string,
+        options?: DefaultOAuthOperationOptions,
+    ): ResultAsync<OAuthTokens, OAuthOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Revoke an access or refresh token, with an optional token-type hint.
+     * The token and hint are captured once when execution starts, then validated and transmitted from that snapshot.
+     * A lost response can still mean the token was revoked.
+     * Network failures retain only sanitized transport facts in cause
+     */
+    revoke(
+        input: {
+            /** Access or refresh token to invalidate. Keep this secret out of logs */
+            readonly token: string
+            /** Identify the token as an access token or a refresh token. Omit when the kind is unknown */
+            readonly tokenTypeHint?: "access_token" | "refresh_token"
+        },
+        options?: DefaultOAuthOperationOptions,
+    ): ResultAsync<void, OAuthOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Fetch the delegated user's identity with an access token granted the identify scope.
+     * Additional identity fields depend on the token's scopes.
+     * The access token is not retained by this client.
+     * Failures identify a read in details.read, so errors.isRetryable can classify transient failures without implying a token change.
+     * Requests are not retried automatically, and network causes retain only sanitized transport facts
+     */
+    fetchIdentity(
+        accessToken: string,
+        options?: DefaultOAuthOperationOptions,
+    ): ResultAsync<OAuthIdentity, OAuthOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Fetch one bounded page of the delegated user's community memberships.
+     * Use an access token with Fluxer's guilds scope.
+     * Optionally supply pagination settings in GuildListQuery, where limit defaults to 200 and accepts 1–200, and before and after are mutually exclusive cursors.
+     * This uses bearer authentication with the supplied access token, never the bot token.
+     * Failures identify a read in details.read for errors.isRetryable. Requests are not retried automatically,
+     * and network causes retain only sanitized transport facts
+     */
+    fetchGuilds(
+        accessToken: string,
+        query?: GuildListQuery,
+        options?: DefaultOAuthOperationOptions,
+    ): ResultAsync<readonly GuildListSummary[], OAuthOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Fetch the delegated user's full connections list with a connections-scoped access token.
+     * The client neither creates, verifies, reorders nor retains those connections.
+     * Failures identify a read in details.read for errors.isRetryable. Requests are not retried automatically,
+     * and network causes retain only sanitized transport facts
+     */
+    fetchConnections(
+        accessToken: string,
+        options?: DefaultOAuthOperationOptions,
+    ): ResultAsync<readonly OAuthConnection[], OAuthOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Inspect an access or refresh token using this client's ID and secret through HTTP Basic authentication.
+     * An inactive result does not explain expiry or revocation, prove token ownership or establish whether it ever existed.
+     * Failures identify a read in details.read for errors.isRetryable. Requests are not retried automatically,
+     * and network causes retain only sanitized transport facts
+     */
+    introspect(
+        token: string,
+        options?: DefaultOAuthOperationOptions,
+    ): ResultAsync<OAuthIntrospection, OAuthOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Permanently stop OAuth work, reject new work, release the client's copied secret and abort active requests.
+     * Shutdown waits for fetch and response-reader cleanup.
+     * A response-cleanup failure in an active operation fails that operation, while shutdown waits for it and may itself succeed.
+     * A failure in shutdown's own discovery cleanup fails shutdown
+     *
+     * @remarks
+     * Those cleanup failures reject with SdkDefect
+     */
+    shutdown(): ResultAsync<void, never>
+    /**
+     * Shut down this client and wait for cleanup, as `await using` does at the end of a block.
+     * Unexpected cleanup failures reject with SdkDefect, as shutdown does
+     */
+    [Symbol.asyncDispose](): Promise<void>
+}
+
+/**
+ * Create confidential OAuth clients and generate PKCE values for authorization-code flows.
+ * Use these helpers on a trusted server where the client secret is not exposed to a browser
+ *
+ * @remarks
+ * The application handles browser navigation, callbacks, state correlation, consent and token storage.
+ * It also decides installation policy and coordinates refreshes.
+ * The create method returns the client synchronously without making a request, and throws ConfigurationError for invalid settings.
+ * The createPkce method returns a new verifier and S256 challenge for the same authorization flow.
+ * PKCE links authorization to the code exchange using a private random verifier and its public SHA-256 hash challenge.
+ * Keep the verifier private and send only the challenge to authorizationUrl
+ *
+ * @example
+ * ```ts
+ * import { oauth, OAuthScopes } from "@neontechspace/fluxerly"
+ *
+ * export async function oauthExample(clientId: string, clientSecret: string, redirectUri: string, state: string) {
+ *     const client = oauth.create({ clientId, clientSecret })
+ *     try {
+ *         const pkce = oauth.createPkce()
+ *         return await client.authorizationUrl({
+ *             redirectUri,
+ *             scopes: [OAuthScopes.Identify, OAuthScopes.Bot],
+ *             state,
+ *             codeChallenge: pkce.challenge,
+ *             guildId: "456",
+ *             permissions: 0n,
+ *         })
+ *     } finally {
+ *         await client.shutdown()
+ *     }
+ * }
+ * ```
+ *
+ * @category OAuth
+ */
+export const oauth: Readonly<{
+    /**
+     * Create a standalone OAuth client with a clientId and server-held clientSecret.
+     * Creation checks configuration synchronously without requests and copies the secret until shutdown.
+     * Invalid settings throw ConfigurationError.
+     * Unexpected creation failures throw SdkDefect with operation oauth.create and without configuration details.
+     * A throwing configuration getter uses code application.defect with the thrown value as its cause
+     */
+    create(config: OAuthConfig): OAuthClient
+    /**
+     * Generate a private verifier and matching S256 challenge for one authorization-code flow.
+     * Send challenge to authorizationUrl and keep verifier privately for exchangeCode.
+     * This synchronous helper returns the values immediately, without a request or token storage.
+     * It does not generate or verify the callback's state value
+     */
+    createPkce: () => OAuthPkce
+}> = Object.freeze({
+    create(config: OAuthConfig): OAuthClient {
+        const scope = Scope.makeUnsafe()
+        const created = fromExit(Effect.runSyncExit(makeOAuthOwner(config, scope)), "oauth.create")
+        if (created.isErr()) throw created.error
+        const owner = created.value
+        const shutdown = () =>
+            new ResultAsync<void, never>(
+                Effect.runPromiseExit(owner.shutdown()).then((exit) => {
+                    const result = fromExit(exit, "shutdown")
+                    if (result.isErr())
+                        throw new SdkDefect("shutdown", Exit.isFailure(exit) ? causeReasons(exit.cause) : [])
+                    return ok(undefined)
+                }),
+            )
+        return Object.freeze({
+            authorizationUrl: (input: OAuthAuthorizationInput, options?: DefaultOAuthOperationOptions) =>
+                executeOperation(
+                    suspendInput(() => owner.authorizationUrl(input, oauthOwnerOptions(options))),
+                    "oauth.authorizationUrl",
+                    options,
+                ),
+            exchangeCode: (input: OAuthCodeExchangeInput, options?: DefaultOAuthOperationOptions) =>
+                executeOperation(
+                    suspendInput(() => owner.exchangeCode(input, oauthOwnerOptions(options))),
+                    "oauth.exchangeCode",
+                    options,
+                ),
+            refresh: (refreshToken: string, options?: DefaultOAuthOperationOptions) =>
+                executeOperation(
+                    suspendInput(() => owner.refresh(refreshToken, oauthOwnerOptions(options))),
+                    "oauth.refresh",
+                    options,
+                ),
+            revoke: (
+                input: { readonly token: string; readonly tokenTypeHint?: "access_token" | "refresh_token" },
+                options?: DefaultOAuthOperationOptions,
+            ) =>
+                executeOperation(
+                    suspendInput(() => owner.revoke(input, oauthOwnerOptions(options))),
+                    "oauth.revoke",
+                    options,
+                ),
+            fetchIdentity: (accessToken: string, options?: DefaultOAuthOperationOptions) =>
+                executeOperation(
+                    suspendInput(() => owner.fetchIdentity(accessToken, oauthOwnerOptions(options))),
+                    "oauth.fetchIdentity",
+                    options,
+                ),
+            fetchGuilds: (accessToken: string, query?: GuildListQuery, options?: DefaultOAuthOperationOptions) =>
+                executeOperation(
+                    suspendInput(() => owner.fetchGuilds(accessToken, query, oauthOwnerOptions(options))),
+                    "oauth.fetchGuilds",
+                    options,
+                ),
+            fetchConnections: (accessToken: string, options?: DefaultOAuthOperationOptions) =>
+                executeOperation(
+                    suspendInput(() => owner.fetchConnections(accessToken, oauthOwnerOptions(options))),
+                    "oauth.fetchConnections",
+                    options,
+                ),
+            introspect: (token: string, options?: DefaultOAuthOperationOptions) =>
+                executeOperation(
+                    suspendInput(() => owner.introspect(token, oauthOwnerOptions(options))),
+                    "oauth.introspect",
+                    options,
+                ),
+            shutdown,
+            [Symbol.asyncDispose]: async () => {
+                await shutdown()
+            },
+        })
+    },
+    createPkce,
+})

package/src/api/default/permissions.ts

@@ -0,0 +1,47 @@
+import type { PermissionInput, PermissionTarget } from "#sdk/permissions"
+import type { ResultAsync } from "neverthrow"
+import type { ChannelOperationFailure } from "#sdk/channels"
+import type { GuildOperationFailure, DefaultGuildOperationOptions } from "#sdk/guilds"
+import type { CancelledError, ConfigurationError } from "#sdk/errors"
+
+/**
+ * Calculate permission flags from supplied data or fresh reads.
+ * A permission value alone does not determine channel visibility, role hierarchy, timeouts or authorization for an action
+ *
+ * @category Roles and permissions
+ */
+export interface PermissionHelpers {
+    /**
+     * Calculate permission flags from supplied guild, member, role and optional channel data.
+     * No request or cache read is made, and connection state is irrelevant, including after client shutdown.
+     * The bigint result ranges from 0n through 18_446_744_073_709_551_615n and preserves unknown flags.
+     * Community owner or base Administrator gets all flags.
+     * Otherwise the calculation applies everyone, combined roles, then member overwrites.
+     * Only the target channel's stored overwrites are used, not its parent category's.
+     * A thread uses the overwrites of the parentChannel supplied with it, then grants SendMessages exactly when
+     * SendMessagesInThreads is granted, as Fluxer does. A thread without its parentChannel, or with any other channel as
+     * parentChannel, is rejected.
+     * Missing or inconsistent input is misuse and throws GuildOperationError for permissions.calculate with reason input in both APIs
+     *
+     * @remarks
+     * Returns the value synchronously.
+     * Unexpected failures throw SdkDefect
+     */
+    calculate(input: PermissionInput): bigint
+    /**
+     * Fetch guild, member, role and optional channel data, then calculate their permission flags.
+     * No gateway connection or cache-first lookup is needed.
+     * A thread channel adds a read of its parent channel, and the result follows Fluxer's thread rule as in calculate.
+     * Underlying reads can enter enabled caches, but the calculated result is not cached.
+     * The sequential reads are separate observations, so the result does not guarantee a later action will succeed.
+     * The default deadline, rest.defaultTimeoutMs (30,000 ms unless configured), covers the whole helper with shared read retries and awaited cancellation cleanup.
+     * Invalid target or deadline fails with permissions.fetch reason input.
+     * Resource errors keep their GuildOperationError or ChannelOperationError.
+     * A channel from another community fails instead of mixing guild data.
+     * Client closure fails with ClientClosedError
+     */
+    fetch(
+        target: PermissionTarget,
+        options?: DefaultGuildOperationOptions,
+    ): ResultAsync<bigint, GuildOperationFailure | ChannelOperationFailure | CancelledError | ConfigurationError>
+}

package/src/api/default/presence.ts

@@ -0,0 +1,88 @@
+import type { PresenceInput, PresenceFailure } from "#sdk/presence"
+import type { Result } from "neverthrow"
+
+/**
+ * Set the bot's displayed status or request updates for selected community members.
+ * Outgoing status is sent to live shards assigned to this client, at least four seconds apart per shard.
+ * Member selections use separate bounded gateway requests.
+ * Neither operation has a provider acknowledgement or recipient-delivery guarantee.
+ * The SDK does not fetch membership or filter out self.
+ * Fluxer decides access and which updates are visible
+ *
+ * @category Client and lifecycle
+ */
+export interface Presence {
+    /**
+     * Set the bot's requested status and optional custom status, including before connecting.
+     * The input is validated and frozen when the call runs.
+     * Omitted customStatus keeps the previous request, and null clears it.
+     * Expired custom statuses are not restored after reconnect.
+     * Each shard retains at most one unsent status update, replacing it with the latest intent even while gateway pacing waits.
+     * The four-second interval starts when an update reaches the socket, not when it is queued.
+     * Success means the request was accepted locally and scheduled for each shard, not acknowledged by Fluxer.
+     * Shutdown releases this intent and its timer
+     *
+     * @remarks
+     * Returns a Result synchronously.
+     * A throwing input getter throws SdkDefect with code application.defect and the thrown value as its cause, and other
+     * unexpected failures throw SdkDefect with code sdk.defect
+     *
+     * @example
+     * ```ts
+     * import { MemberMentionPreferences, type Client } from "@neontechspace/fluxerly"
+     * export async function botProfileExample(client: Client, guildId: string) {
+     *     const presence = client.presence.set({ status: "online", customStatus: { text: "Ready", emoji: { name: "🌱" } } })
+     *     if (presence.isErr()) return presence
+     *     return client.members.editSelf(guildId, { nickname: "Support", mentionFlags: MemberMentionPreferences.PreferNoMention })
+     * }
+     * ```
+     */
+    set(input: PresenceInput): Result<void, PresenceFailure>
+    /**
+     * Request presence updates for selected members in one community.
+     * Register a presenceUpdate listener, then pass accessible non-self member IDs.
+     * Pass [] to clear the selection.
+     * Closing the listener does not clear it.
+     * No full-member subscription, member lookup or presence cache is created, and Fluxer remains authoritative for access and filtering.
+     * The community must belong to a shard assigned to this client, or the call fails with PresenceError reason input
+     *
+     * Inputs are copied and retained when the call runs.
+     * Up to 1,000 distinct decimal IDs are accepted, but the full UTF-8 gateway frame must fit 4,096 bytes.
+     * Long IDs therefore reduce the effective per-community maximum.
+     * The client retains selections for at most 100 communities and 10,000 IDs.
+     * Clearing an unsent selection withdraws its queued command and releases its slot immediately.
+     * Changes to a selection that has not reached the socket replace that unsent request.
+     * Clearing a selection already sent keeps one bounded session slot until fresh Identify or confirmed community leave, because a local socket write cannot confirm that Fluxer applied a clear
+     *
+     * After READY or RESUMED, the latest selection or clear is combined and sent at most once per 125 ms per shard.
+     * This interval starts at actual socket transmission, and at most one member-selection command waits per shard.
+     * Sending the same list again deliberately requests a refresh.
+     * A matching guild creation also retries the latest selection or a previously sent clear.
+     * None of these attempts guarantees an event or proves provider acceptance.
+     * Initial state and transitions can be missed during recovery.
+     * Loss of shared channel visibility can remove the provider subscription, so resend the selection after access returns.
+     * Clear explicitly or shut down the client to release local intent.
+     * Input or limit failures fail with PresenceError, and closing clients fail with ClientClosedError.
+     * The community and member IDs must be positive decimal strings without leading zeros, no greater than 9223372036854775807.
+     * The member IDs are copied once, and that copy is validated and subscribed
+     *
+     * @remarks
+     * Returns a Result synchronously.
+     * A throwing ID getter throws SdkDefect with code application.defect and the thrown value as its cause, and other
+     * unexpected failures throw SdkDefect with code sdk.defect
+     *
+     * @example
+     * ```ts
+     * import type { Client } from "@neontechspace/fluxerly"
+     * export function watchSelectedMember(client: Client, guildId: string, memberId: string) {
+     *     const subscription = client.on("presenceUpdate", (presence) => {
+     *         if (presence.guildId === guildId && presence.userId === memberId) void presence.status
+     *     })
+     *     const selected = client.presence.setMembers(guildId, [memberId])
+     *     if (selected.isErr()) subscription.close()
+     *     return selected.map(() => subscription)
+     * }
+     * ```
+     */
+    setMembers(guildId: string, memberIds: readonly string[]): Result<void, PresenceFailure>
+}

package/src/api/default/rest.ts

@@ -0,0 +1,30 @@
+import type { ResultAsync } from "neverthrow"
+import type { CancelledError, ConfigurationError } from "#sdk/errors"
+import type { DefaultRestRequest, RestRequestFailure, RestResponse } from "#sdk/rest"
+
+/**
+ * Send requests to Fluxer API routes that the SDK does not wrap, with the client's bot credential and its REST scheduler.
+ * Calls start immediately, need no gateway connection and default to the client's rest.defaultTimeoutMs deadline.
+ * Abort waits for cleanup and returns CancelledError. Unexpected failures reject with SdkDefect
+ *
+ * @category Client and lifecycle
+ */
+export interface RestRequests {
+    /**
+     * Send one request to a route under /v1 and resolve with its status, lower-case headers and parsed JSON body.
+     * The request waits in the client's queue and learned rate-limit windows like wrapped operations, and fails at once
+     * with reason rateLimit and the remaining wait as retryAfterMs when a window outlasts the deadline. A 429 is waited
+     * out and sent again while the deadline allows. A GET is also retried at most twice after a network error, including
+     * a connection lost while the response body arrives, or HTTP 500, 502, 503 or 504. Another method is never sent
+     * again after an uncertain outcome.
+     * Invalid input fails with RestRequestError reason input before any request, a non-2xx status fails with its status
+     * and sanitized apiError, and closure fails with ClientClosedError. Message and resource caches are not updated.
+     * Percent-encoded unreserved letters cannot bypass the reserved /v1 prefix or token-webhook route checks, which remain case-sensitive.
+     * Network causes retain sanitized transport facts, not raw errors. Unknown uppercase provider codes remain in details.providerCode,
+     * including on HTTP 429 when its wait exceeds the deadline.
+     * Logs, metrics and spans name only the route template, never the query, body or response
+     */
+    request<T = unknown>(
+        input: DefaultRestRequest,
+    ): ResultAsync<RestResponse<T>, RestRequestFailure | CancelledError | ConfigurationError>
+}

package/src/api/default/results.ts

@@ -0,0 +1,44 @@
+import type { Result } from "neverthrow"
+
+/**
+ * Return the value of an Ok result, or throw the error of an Err result.
+ * Use it where a failure should end the surrounding function, such as a command handler whose thrown error is
+ * reported with the command name, or a startup script that should stop with the SDK's message and hint.
+ * The thrown value is the operation's own error, so its message, hint, code and cause remain available
+ *
+ * @remarks
+ * A ResultAsync, or any promise of a Result, returns a Promise that resolves with the value or rejects with the error.
+ * Keep checking isErr() where the application must recover from a particular failure instead
+ *
+ * @example
+ * ```ts
+ * import { orThrow, type Client } from "@neontechspace/fluxerly"
+ *
+ * export async function greet(client: Client, channelId: string) {
+ *     const message = orThrow(await client.messages.send(channelId, { content: "Hello" }))
+ *     return orThrow(client.messages.edit(message, { content: "Hello again" }))
+ * }
+ * ```
+ *
+ * @category Errors
+ */
+export function orThrow<T, E>(result: Result<T, E>): T
+/**
+ * Wait for a ResultAsync, or any promise of a Result, and resolve with its value or reject with its error
+ *
+ * @category Errors
+ */
+export function orThrow<T, E>(result: PromiseLike<Result<T, E>>): Promise<T>
+export function orThrow<T, E>(result: Result<T, E> | PromiseLike<Result<T, E>>): T | Promise<T> {
+    if (isPromiseLike(result)) return Promise.resolve(result).then(unwrap)
+    return unwrap(result)
+}
+
+function unwrap<T, E>(result: Result<T, E>): T {
+    if (result.isErr()) throw result.error
+    return result.value
+}
+
+function isPromiseLike<A>(value: A | PromiseLike<A>): value is PromiseLike<A> {
+    return typeof (value as { then?: unknown }).then === "function"
+}

package/src/api/default/roles.ts

@@ -0,0 +1,154 @@
+import type { ResultAsync } from "neverthrow"
+import type {
+    GuildRole,
+    RoleReference,
+    RolePosition,
+    RoleHoistPosition,
+    RoleCreate,
+    RoleEdit,
+    GuildOperationFailure,
+    DefaultGuildOperationOptions,
+    DefaultGuildAuditOperationOptions,
+} from "#sdk/guilds"
+import type { CancelledError, ConfigurationError } from "#sdk/errors"
+
+/**
+ * Create, edit, order and delete community roles, or read their current or cached data.
+ * Shared Guilds request limits, deadlines and read retries apply.
+ * Fluxer enforces permissions and hierarchy.
+ * No local permission prediction is performed
+ *
+ * Writes retry only confirmed HTTP 429 rejection.
+ * Abort waits for request cleanup but cannot undo a dispatched write
+ *
+ * Expected failures return GuildOperationError or ClientClosedError.
+ * Unexpected failures reject with SdkDefect.
+ * Inputs are copied when called.
+ * Results are snapshots, not gateway acknowledgement.
+ * Role permissions use bigint, which requires explicit conversion before JSON serialization.
+ * Every remote role mutation accepts DefaultGuildAuditOperationOptions. The fetchAll method rejects auditReason
+ *
+ * @category Roles and permissions
+ */
+export interface Roles {
+    /**
+     * Look up a role by decimal guildId and id in the enabled cache, including the everyone role.
+     * No request is made.
+     * The cache misses, stale-snapshot warnings, misuse and recency rules of guilds.get apply
+     *
+     * @remarks
+     * Returns the value synchronously.
+     * Unexpected failures throw SdkDefect
+     */
+    get(role: RoleReference): GuildRole | undefined
+    /**
+     * Fetch the community's current role list, including everyone, in server order.
+     * This always reads remotely, without pagination or background refresh
+     */
+    fetchAll(
+        guildId: string,
+        options?: DefaultGuildOperationOptions,
+    ): ResultAsync<readonly GuildRole[], GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Create a role with a name, optional color and permission flags.
+     * The permissions input defaults to 0n, rather than copying the everyone role's grants.
+     * Supplied permissions must be from 0n through 9_223_372_036_854_775_807n.
+     * Explicit permissions use Fluxer's feature opt-in for ViewChannelMembers.
+     * The result reports the actual server grants, which can differ from the request.
+     * Use a separate edit to change hoist or mentionable settings.
+     * The application manages the created role afterward.
+     * After an unknown outcome, use fetchAll before deciding whether to create again
+     *
+     * @example
+     * ```ts
+     * import { Permissions, type Client } from "@neontechspace/fluxerly"
+     * export async function createRoleExample(client: Client, guildId: string) {
+     *     const result = await client.roles.create(guildId, {
+     *         name: "Readers",
+     *         permissions: Permissions.ViewChannel | Permissions.ReadMessageHistory,
+     *     })
+     *     if (result.isErr()) throw result.error
+     *     return result.value
+     * }
+     * ```
+     */
+    create(
+        guildId: string,
+        input: RoleCreate,
+        options?: DefaultGuildAuditOperationOptions,
+    ): ResultAsync<GuildRole, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Change only supplied role fields and return the server's snapshot.
+     * Empty inputs and unknown fields fail locally.
+     * The permissions input replaces all raw grants rather than adding flags, and can set or clear ViewChannelMembers.
+     * The replacement must be from 0n through 9_223_372_036_854_775_807n, and larger received masks cannot be written unchanged.
+     * The everyone role accepts only color and permissions.
+     * Other supplied fields fail, even in a mixed input
+     */
+    edit(
+        role: RoleReference,
+        input: RoleEdit,
+        options?: DefaultGuildAuditOperationOptions,
+    ): ResultAsync<GuildRole, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Delete a role and remove its member assignments in Fluxer.
+     * The everyone role cannot be deleted.
+     * Fluxer removes the role from each member in separate writes before it deletes the role, and does not roll them back.
+     * A failure can leave the role in place after some members already lost it, so fetch the role and the affected members again before retrying.
+     * HTTP 204 succeeds with no value, without proving member-event delivery.
+     * Snapshots already returned to the caller remain unchanged
+     */
+    delete(
+        role: RoleReference,
+        options?: DefaultGuildAuditOperationOptions,
+    ): ResultAsync<void, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Change role hierarchy positions using distinct role IDs and nonnegative safe-integer positions.
+     * The everyone role cannot move.
+     * HTTP 204 succeeds with no value and no new role list.
+     * Fluxer normalizes manageable positions, so use fetchAll if final order matters.
+     * This is not a transaction.
+     * A failure can leave partial changes, requiring a fresh read before recovery
+     */
+    reorder(
+        guildId: string,
+        positions: readonly RolePosition[],
+        options?: DefaultGuildAuditOperationOptions,
+    ): ResultAsync<void, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Set roles' display positions without changing their permission hierarchy or enabling hoist.
+     * Pass a nonempty list of distinct role IDs with integer hoistPosition values from -2,147,483,648 through 2,147,483,647.
+     * The everyone role is excluded.
+     * Fluxer checks ManageRoles and hierarchy.
+     * HTTP 204 succeeds with no value, not a role list.
+     * Successful writes and writes with unknown outcomes invalidate cached guild roles and conflicting pending reads.
+     * Failure or cancellation can leave partial changes.
+     * Refetch before deciding to replay
+     *
+     * @example
+     * ```ts
+     * import { type Client } from "@neontechspace/fluxerly"
+     * export function orderRoleDisplay(client: Client, guildId: string, roleId: string) {
+     *     return client.roles.setHoistPositions(guildId, [{ id: roleId, hoistPosition: 0 }])
+     * }
+     * ```
+     */
+    setHoistPositions(
+        guildId: string,
+        positions: readonly RoleHoistPosition[],
+        options?: DefaultGuildAuditOperationOptions,
+    ): ResultAsync<void, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Clear display-position assignments across the community, including roles above the bot.
+     * Fluxer requires ManageRoles.
+     * Permission hierarchy and hoist flags remain unchanged.
+     * HTTP 204 succeeds with no value, not a role list.
+     * Changes are not transactional and a failure can be partial.
+     * Successful writes and writes with unknown outcomes invalidate cached guild roles.
+     * Refetch to resolve an unknown outcome
+     */
+    resetHoistPositions(
+        guildId: string,
+        options?: DefaultGuildAuditOperationOptions,
+    ): ResultAsync<void, GuildOperationFailure | CancelledError | ConfigurationError>
+}