@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/api/default/application.ts

@@ -0,0 +1,40 @@
+import type {
+    BotApplication,
+    BotApplicationOperationFailure,
+    DefaultBotApplicationOperationOptions,
+} from "#sdk/application"
+import type { ResultAsync } from "neverthrow"
+import type { CancelledError, ConfigurationError } from "#sdk/errors"
+
+/**
+ * Read the authenticated bot's application identity, its owner's user ID and selected public settings.
+ * No gateway connection, application management or authorization-page navigation is performed.
+ * The GET uses shared request limits, the client's default deadline (rest.defaultTimeoutMs, 30,000 ms unless configured) and at most two transient read retries.
+ * The frozen result is not cached.
+ * Of the owner only the user ID is kept, and redirect URIs, verification keys, client secrets and nested bot fields are excluded.
+ * Fluxer decides application visibility and installability.
+ * Input, HTTP and malformed-response failures return BotApplicationOperationError.
+ * Closure returns ClientClosedError.
+ * Abort waits for cleanup and returns CancelledError.
+ * Unexpected failures reject with SdkDefect
+ *
+ * @example
+ * ```ts
+ * import { links, type Client } from "@neontechspace/fluxerly"
+ * export async function applicationExample(client: Client) {
+ *     const application = await client.application.fetch()
+ *     return application.isErr() ? application : links.installation(application.value.id, { permissions: 0n })
+ * }
+ * ```
+ *
+ * @category Client and lifecycle
+ */
+export interface CurrentBotApplication {
+    /**
+     * Fetch this bot token's application data from /oauth2/applications/@me.
+     * Only the documented fields are returned, frozen, without cache storage, gateway events, owner profile lookup or follow-up requests
+     */
+    fetch(
+        options?: DefaultBotApplicationOperationOptions,
+    ): ResultAsync<BotApplication, BotApplicationOperationFailure | CancelledError | ConfigurationError>
+}

package/src/api/default/attachments.ts

@@ -0,0 +1,106 @@
+import type {
+    Attachment,
+    AttachmentDownloadFailure,
+    AttachmentRefreshFailure,
+    DefaultAttachmentRefreshOptions,
+    DefaultAttachmentDownloadOptions,
+    DefaultAttachmentStreamOptions,
+    RefreshedAttachmentUrl,
+} from "#sdk/attachments"
+import type { ResultAsync, Result } from "neverthrow"
+import type { CancelledError, ConfigurationError } from "#sdk/errors"
+
+/**
+ * Refresh signed attachment URL strings explicitly, or download received Attachment data all at once or as chunks.
+ * Refresh uses the selected instance's authenticated API. Downloads use its media path, with no gateway connection or cache required.
+ * The SDK never sends bot credentials to a download URL or substitutes attachment.proxyUrl
+ *
+ * @category Messages
+ */
+export interface Attachments {
+    /**
+     * Ask Fluxer's bot-authenticated API to reissue signatures for 1 through 50 URL strings.
+     * Each string may contain at most 2,048 UTF-16 code units.
+     * Strings, duplicate entries and query parameters are sent unchanged
+     *
+     * The frozen result has one original and refreshed pair per input in the same order.
+     * A string outside this instance's attachment URL space is returned unchanged by Fluxer.
+     * Refreshing does not check attachment existence, community or channel membership, permission to download, or media availability
+     *
+     * This method never downloads media and sends the bot credential only to the selected instance's API, never to a requested or refreshed URL.
+     * The credentialed POST follows no redirect.
+     * Use download explicitly afterward for a returned URL that belongs to this instance
+     *
+     * The timeoutMs option defaults to the client's rest.defaultTimeoutMs, 30,000 unless configured, for endpoint discovery, waiting for a REST request slot, rate-limit waits and the limited response read.
+     * A confirmed 429 can retry after its required wait.
+     * A POST with an unknown outcome or a malformed success is not retried automatically.
+     * Cancellation affects only this refresh and waits for request cleanup.
+     * HTTP 404 cannot distinguish an older unsupported deployment from an unavailable route or denied access.
+     * No refresh happens automatically when reading messages or downloading attachments
+     */
+    refreshUrls(
+        urls: readonly string[],
+        options?: DefaultAttachmentRefreshOptions,
+    ): ResultAsync<readonly RefreshedAttachmentUrl[], AttachmentRefreshFailure | CancelledError | ConfigurationError>
+    /**
+     * Download attachment.url into one Uint8Array.
+     * Pass maxBytes explicitly, from 1 through 52,428,800 bytes (50 MiB).
+     * The limit caps the returned bytes, not total memory, because response chunks can coexist with the packed result
+     *
+     * The URL must match this instance's discovered media /attachments/ path.
+     * The GET sends no Authorization header, follows no redirects, stores no cached copy and never falls back to proxyUrl.
+     * The timeoutMs option defaults to the client's rest.defaultTimeoutMs, 30,000 unless configured, for endpoint discovery, waiting for a media slot and downloading.
+     * By default four media downloads can run at once (rest.mediaConcurrency), separately from REST and uploads, without waiting for bot API rate limits.
+     * Cancellation waits for response-reader cleanup, but cannot undo bytes already received
+     *
+     * Size and expiry metadata do not prove that the URL is available or the bytes are safe.
+     * Expected failures contain a safe reason and status, including busy, without the URL or response body.
+     * Discovery and download transport failures retain a sanitized cause with a safe transport code when available, never the raw error
+     */
+    download(
+        attachment: Attachment,
+        options: DefaultAttachmentDownloadOptions,
+    ): ResultAsync<Uint8Array, AttachmentDownloadFailure | CancelledError | ConfigurationError>
+    /**
+     * Read attachment.url as chunks without combining the file into one array.
+     * Pass maxBytes explicitly, from 1 through 52,428,800 bytes (50 MiB), for the total bytes delivered
+     *
+     * The first pull reads the inputs, resolves endpoints, waits for a media slot (four by default, rest.mediaConcurrency) and starts the GET.
+     * Media slots are separate from the REST and upload slots.
+     * Later pulls read at most one response chunk.
+     * No byte packing, spooling, automatic retry or durable storage is added
+     *
+     * The URL must match this instance's media /attachments/ path.
+     * The GET sends no Authorization header, follows no redirects, caches nothing and never uses proxyUrl.
+     * A Content-Length above maxBytes fails before any chunk, but actual byte counting is still enforced
+     *
+     * The result can be consumed only once.
+     * The timeoutMs option defaults to the client's rest.defaultTimeoutMs, 30,000 unless configured, for the whole download, including pauses between chunks.
+     * Ending consumption early, cancellation, failure and client shutdown cancel the body, wait for reader cleanup and release the media slot.
+     * Expected failures include safe local busy, network, response, limit and deadline reasons and client closure.
+     * Transport failures during discovery, opening or reading retain sanitized causes with safe transport codes when available, never raw errors.
+     * Size and expiry metadata do not establish availability or byte safety
+     *
+     * @remarks
+     * Consume the iterable with a for await loop.
+     * Each item is a Result containing one Uint8Array, and an expected failure yields one Err and ends the loop.
+     * Overlapping next calls return busy without cancelling the pending read.
+     * Breaking the loop, return, throw and signal cancellation all end the download.
+     * Listener or cleanup failures reject with SdkDefect after independent cleanup is attempted
+     *
+     * @example
+     * ```ts
+     * import type { Attachment, Client } from "@neontechspace/fluxerly"
+     * export async function downloadChunks(client: Client, attachment: Attachment) {
+     *     for await (const chunk of client.attachments.stream(attachment, { maxBytes: 1_024 })) {
+     *         if (chunk.isErr()) return chunk
+     *         void chunk.value
+     *     }
+     * }
+     * ```
+     */
+    stream(
+        attachment: Attachment,
+        options: DefaultAttachmentStreamOptions,
+    ): AsyncIterable<Result<Uint8Array, AttachmentDownloadFailure | CancelledError | ConfigurationError>>
+}

package/src/api/default/audit-logs.ts

@@ -0,0 +1,58 @@
+import type { AuditLogEntry, AuditLogPage, AuditLogQuery, AuditLogIterationQuery } from "#sdk/audit-logs"
+import type { PaginationError } from "#sdk/pagination"
+import type { ResultAsync, Result } from "neverthrow"
+import type { GuildOperationFailure, DefaultGuildOperationOptions } from "#sdk/guilds"
+import type { CancelledError, ConfigurationError } from "#sdk/errors"
+
+/**
+ * Read a community's audit log with ViewAuditLog permission, without connecting the gateway.
+ * The fetchPage method starts immediately.
+ * The iterate method reads pages only when the loop requests them.
+ * The SDK does not cache audit records or create a permanent archive.
+ * Guilds' shared request limits, deadlines and eligible read retries apply.
+ * Input, permission and malformed-response failures return GuildOperationError.
+ * Abort waits for cleanup and returns CancelledError.
+ * Closing clients return ClientClosedError.
+ * Unexpected failures reject with SdkDefect.
+ * Records can change independently between reads
+ *
+ * @category Guilds and members
+ */
+export interface AuditLogs {
+    /**
+     * Fetch one filtered audit page with referenced users and webhook metadata that excludes tokens.
+     * Supply cursors and filters in AuditLogQuery.
+     * A deletion duration that cannot be represented as safe integer milliseconds fails with reason response, without returning a partial page.
+     * The returned page is frozen and remains in memory while the caller retains it
+     */
+    fetchPage(
+        guildId: string,
+        query: AuditLogQuery,
+        options?: DefaultGuildOperationOptions,
+    ): ResultAsync<AuditLogPage, GuildOperationFailure | CancelledError | ConfigurationError>
+    /**
+     * Read filtered audit entries newest first, buffering one page and never prefetching.
+     * The maxItems option is required.
+     * The pageSize option defaults to 50 and accepts 1–100, maxPages defaults to 100, and timeoutMs applies to each page.
+     * An empty page or maxItems ends the scan, not a short page.
+     * Invalid traversal input, a stalled cursor or reaching the page budget fails with PaginationError.
+     * Remote failures keep auditLogs.fetchPage's errors.
+     * Deletion durations are rounded to whole milliseconds, and one whose milliseconds are not a safe integer fails its page before that page's entries are delivered.
+     * Each consumption is independent, and client closure releases the page and fails the next pull.
+     * Already delivered entries remain with the caller, and concurrent changes can prevent a complete scan.
+     * Use fetchPage instead to also receive referenced users or webhooks
+     *
+     * @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
+     */
+    iterate(
+        guildId: string,
+        query: AuditLogIterationQuery,
+        options?: DefaultGuildOperationOptions,
+    ): AsyncIterable<
+        Result<AuditLogEntry, GuildOperationFailure | PaginationError | CancelledError | ConfigurationError>
+    >
+}