@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/api/default/helpers.ts

@@ -0,0 +1,97 @@
+import {
+    type FormatHelpers,
+    type SnowflakeHelpers,
+    type DisplayHelpers,
+    type PermissionBitHelpers,
+    type LinkHelpers,
+    display as sharedDisplay,
+    format as sharedFormat,
+    links as sharedLinks,
+    permissionBits as sharedPermissionBits,
+    snowflakes as sharedSnowflakes,
+} from "#sdk/helpers"
+import { type ColorHelpers, colors as sharedColors } from "#sdk/colors"
+import { type TextHelpers, text as sharedText } from "#sdk/text"
+import { type AssetHelpers, assets as sharedAssets } from "#sdk/assets"
+
+/**
+ * Create Fluxer markup for mentions, timestamps, custom emoji and Markdown escaping.
+ * Use these helpers when building message content, without creating a client or making a request.
+ * Helpers return plain values and throw HelperError for invalid input, which indicates a programming mistake.
+ * For text received from users, tryParseMention, tryParseTimestamp and tryParseCustomEmoji return a Result instead of throwing.
+ * Check isOk() before reading value, or isErr() before reading error.
+ * A mention in the text does not enable notifications, which are controlled by allowedMentions when sending
+ *
+ * @category Builders and formatting
+ */
+export const format: FormatHelpers = sharedFormat
+
+/**
+ * Read and convert Fluxer's IDs, called snowflakes, without losing integer precision.
+ * Keep IDs as decimal strings rather than JavaScript numbers.
+ * Conversions return plain values and throw HelperError for an invalid ID or Date.
+ * For IDs received from users, tryParse returns a Result instead of throwing
+ *
+ * @category Builders and formatting
+ */
+export const snowflakes: SnowflakeHelpers = sharedSnowflakes
+
+/**
+ * Choose a display name from supplied user or member data.
+ * No account request or cache lookup is made
+ *
+ * @category Builders and formatting
+ */
+export const display: DisplayHelpers = sharedDisplay
+
+/**
+ * Build and inspect raw permission flags with bigint values.
+ * Use from to combine named permissions, missing to find absent names, and toDecimal to produce a decimal string.
+ * Each helper returns a plain value and throws HelperError for unknown names or bits outside the unsigned 64-bit range.
+ * These helpers inspect flags only, not whether Fluxer will allow a particular action
+ *
+ * @category Roles and permissions
+ */
+export const permissionBits: PermissionBitHelpers = sharedPermissionBits
+
+/**
+ * Convert supported RGB numbers, six-digit hex strings and RGB tuples into colors.
+ * Invalid input throws HelperError rather than being converted automatically.
+ * For colors received from users, tryParse returns a Result instead of throwing.
+ * No client or network request is needed
+ *
+ * @category Builders and formatting
+ */
+export const colors: ColorHelpers = sharedColors
+
+/**
+ * Split a string into frozen pieces without dropping or changing its text.
+ * The maxLength option counts UTF-16 code units, as JavaScript string.length does.
+ * The pieces are returned directly, and invalid text or options throw HelperError.
+ * This helper neither sends the pieces nor repairs Markdown split across them
+ *
+ * @category Builders and formatting
+ */
+export const text: TextHelpers = sharedText
+
+/**
+ * Build links to Fluxer channels, direct messages, messages and bot installation pages.
+ * These helpers use hosted Fluxer URLs.
+ * Each helper returns the URL directly, and invalid route inputs throw HelperError.
+ * Building a link does not check access or install the bot
+ *
+ * @category Builders and formatting
+ */
+export const links: LinkHelpers = sharedLinks
+
+/**
+ * Build hosted Fluxer URLs for avatars, banners, community images, emoji and stickers.
+ * Calls return the URL, null or undefined directly and throw AssetUrlError for invalid input.
+ * They do not download the image or need a client.
+ * Use client.instance.resolve() for helpers tied to a self-hosted instance instead.
+ * Member avatar and banner helpers read only guildId, userId and the chosen image hash.
+ * The displayMemberAvatar helper also reads profileFlags to choose the fallback image
+ *
+ * @category Builders and formatting
+ */
+export const assets: AssetHelpers = sharedAssets

package/src/api/default/instance.ts

@@ -0,0 +1,49 @@
+import type { ResultAsync } from "neverthrow"
+import type { OperationOptions } from "#sdk/client"
+import type { InstanceResolveError, InstanceResolveOptions, ResolvedInstance } from "#sdk/instance"
+import type { CancelledError, ConfigurationError } from "#sdk/errors"
+
+/**
+ * Find the selected Fluxer instance's endpoints and build links and asset URLs for it.
+ * The resolve method fetches the unauthenticated well-known document only when needed.
+ * Concurrent callers share that request.
+ * A successful frozen result is retained until client shutdown, without background refresh.
+ * Cancelling one caller leaves other callers using the request.
+ * The last departing caller waits for discovery cleanup
+ *
+ * @example
+ * ```ts
+ * import type { Client } from "@neontechspace/fluxerly"
+ * export async function instanceExample(client: Client) {
+ *     const resolved = await client.instance.resolve({ timeoutMs: 10_000 })
+ *     if (resolved.isErr()) return resolved
+ *     const channel = resolved.value.links.channel({ id: "1750000000000000000" })
+ *     return { api: resolved.value.endpoints.apiPublic, channel }
+ * }
+ * ```
+ *
+ * @category Client and lifecycle
+ */
+export interface Instance {
+    /**
+     * Resolve this client's instance endpoints and its pure link and asset URL helpers.
+     * The unauthenticated discovery request is shared with other resolves, REST work or gateway startup.
+     * The timeoutMs option defaults to 30,000 for this wait only.
+     * Cancellation releases only this wait, while other users can keep the shared discovery read alive.
+     * Document, rate-limit, timeout, closure and invalid timeout-option failures are expected failures
+     *
+     * @remarks
+     * Unexpected cleanup failures reject with SdkDefect, retaining safe details of any accompanying failure or interruption
+     */
+    resolve(
+        options?: DefaultInstanceResolveOptions,
+    ): ResultAsync<ResolvedInstance, InstanceResolveError | CancelledError | ConfigurationError>
+}
+
+/**
+ * Set the discovery-wait timeout in milliseconds and optionally pass an AbortSignal.
+ * The signal cancels only this caller's wait
+ *
+ * @category Options
+ */
+export interface DefaultInstanceResolveOptions extends InstanceResolveOptions, OperationOptions {}

package/src/api/default/invites.ts

@@ -0,0 +1,73 @@
+import type { Invite, InviteCreate, InviteMetadata } from "#sdk/invites"
+import type { ResultAsync } from "neverthrow"
+import type { GuildOperationFailure, DefaultGuildOperationOptions, DefaultModerationOptions } from "#sdk/guilds"
+import type { CancelledError, ConfigurationError } from "#sdk/errors"
+
+/**
+ * Inspect, create, list and revoke invite codes with the bot's credentials.
+ * No gateway connection or invite cache is needed.
+ * Fluxer checks destination visibility, invite permissions and capacity.
+ * Shared guild request limits and deadlines apply.
+ * Eligible reads retry at most twice.
+ * Writes retry only confirmed HTTP 429 rejections
+ *
+ * Expected failures return GuildOperationError or ClientClosedError.
+ * Abort returns CancelledError after cleanup.
+ * Unexpected failures reject with SdkDefect.
+ * A lost write response can leave the invite change applied.
+ * Check remote state before retrying
+ *
+ * @category Invites and webhooks
+ */
+export interface Invites {
+    /**
+     * Look up an invite code without using it or joining its destination.
+     * Pass the code, not its full URL.
+     * Expired, revoked or inaccessible codes fail remotely.
+     * Fluxer may normalize the case of a vanity code
+     */
+    fetch(
+        code: string,
+        options?: DefaultGuildOperationOptions,
+    ): ResultAsync<Invite, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Create an invite for an accessible channel, including an existing group direct message.
+     * Defaults are a new code, 86,400 seconds, unlimited uses and non-temporary membership.
+     * The result is invite metadata.
+     * The SDK does not send the code, create a group or add members.
+     * Cancellation cannot revoke an invite that was already created.
+     * After an unknown outcome, list the destination's invites before deciding whether to create again
+     */
+    create(
+        channelId: string,
+        input?: InviteCreate,
+        options?: DefaultModerationOptions,
+    ): ResultAsync<InviteMetadata, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * List a channel's management-visible invites in Fluxer's order.
+     * Channel permissions determine access.
+     * Concurrent changes can make the list stale, so it is not a stable snapshot
+     */
+    fetchForChannel(
+        channelId: string,
+        options?: DefaultGuildOperationOptions,
+    ): ResultAsync<readonly InviteMetadata[], GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * List a community's management-visible invites with ManageGuild permission.
+     * The community's vanity invite is excluded
+     */
+    fetchForGuild(
+        guildId: string,
+        options?: DefaultGuildOperationOptions,
+    ): ResultAsync<readonly InviteMetadata[], GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Revoke an invite code, succeeding with no value after HTTP 204.
+     * Fluxer checks creator or management permissions.
+     * Existing members remain.
+     * A missing code is an error, not proof a previous delete succeeded
+     */
+    delete(
+        code: string,
+        options?: DefaultModerationOptions,
+    ): ResultAsync<void, GuildOperationFailure | CancelledError | ConfigurationError>
+}

package/src/api/default/logging.ts

@@ -0,0 +1,37 @@
+import type { LogLevelSettings } from "#sdk/logging"
+
+/**
+ * Change what this client logs while it runs.
+ * Creation settings other than level, categories and debug, such as sink and format, stay fixed for the client's lifetime
+ *
+ * @category Logging and diagnostics
+ */
+export interface ClientLogging {
+    /**
+     * Replace the client's log level and per-category levels, and optionally its Debug categories, effective for the next record.
+     * The settings are validated like level, categories and debug in the logging option of createClient.
+     * Omitted level and categories return to their defaults, level info without category levels, as at creation.
+     * An omitted debug keeps the current Debug categories, which start as the debug creation setting plus FLUXERLY_DEBUG.
+     * A debug value replaces them, including those from FLUXERLY_DEBUG.
+     * Pass true for every category, a list for only those categories, or false or an empty list for none.
+     * Debug categories lower their threshold to Debug, never raise it.
+     * It works before, during and after a connection, and changes nothing else about the client
+     *
+     * @remarks
+     * Returns synchronously. Invalid settings, including keys other than level, categories and debug, throw
+     * ConfigurationError and leave the previous settings in place. A throwing settings getter throws SdkDefect with code
+     * application.defect
+     *
+     * @example
+     * ```ts
+     * import type { Client } from "@neontechspace/fluxerly"
+     * export function traceRequests(client: Client) {
+     *     client.logging.configure({ categories: { rest: "debug" } })
+     * }
+     * export function stopDebugOutput(client: Client) {
+     *     client.logging.configure({ debug: false })
+     * }
+     * ```
+     */
+    configure(settings: LogLevelSettings): void
+}