@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/embeds.ts

@@ -0,0 +1,253 @@
+/** A card for a message's `embeds` array, with optional text, images and named sections.
+ * Message operations reject unknown keys and null values locally
+ *
+ * Text length limits count UTF-16 code units, the units used by JavaScript string length. For validation, the SDK removes
+ * U+000C and U+202E and trims surrounding whitespace. It sends the original text unchanged
+ *
+ * URLs must use HTTP/HTTPS and contain at most 2048 characters, except image and thumbnail URLs may use attachment://filename.
+ * An attachment URL must exactly and case-sensitively match one new upload filename in the same send, reply or edit.
+ * Its extension must map to an image or video MIME type in Fluxer's filename lookup, such as PNG, AVIF, MP4 or WebM.
+ * Its filename may contain letters, marks, numbers, underscores, dots and hyphens only
+ *
+ * The SDK does not look up existing attachments, so an existing attachment ID cannot supply an attachment URL.
+ * Fluxer moves referenced uploads into embed media, so they are not returned in the message's attachment list
+ *
+ * Fluxer fetches remote media and may normalize text. Permissions and instance-specific limits remain server-owned
+ * @example
+ * ```ts
+ * import type { EmbedInput } from "@neontechspace/fluxerly"
+ *
+ * export const exampleEmbed = {
+ *     title: "Build finished",
+ *     description: "Checks passed",
+ *     url: "https://example.com/builds/42",
+ *     color: 0x3d66b8,
+ *     timestamp: "2026-09-08T14:30:00.000Z",
+ *     author: { name: "Build service", url: "https://example.com", iconUrl: "https://example.com/author.png" },
+ *     footer: { text: "Build #42", iconUrl: "https://example.com/footer.png" },
+ *     image: { url: "https://example.com/results.png", description: "Build results" },
+ *     thumbnail: { url: "https://example.com/icon.png", description: "Project icon" },
+ *     fields: [{ name: "Status", value: "Passed", inline: true }, { name: "Details", value: "" }],
+ * } satisfies EmbedInput
+ * ```
+ * Pass this object in the embeds array of send, reply or edit. The example URLs are placeholders
+ *
+ * @category Messages
+ */
+export interface EmbedInput {
+    /** Heading text, up to 256 normalized UTF-16 code units. Supply url to make it a link */
+    readonly title?: string
+    /** Main body text. An empty string is omitted by Fluxer. A nonempty value must contain 1–4,096 normalized UTF-16 code units */
+    readonly description?: string
+    /** Destination URL for the title */
+    readonly url?: string
+    /** RGB integer from 0x000000 through 0xffffff */
+    readonly color?: number
+    /** Time shown with the embed, an ISO 8601 string with a timezone such as `new Date().toISOString()`.
+     * Invalid calendar dates are rejected locally
+     */
+    readonly timestamp?: string
+    /** Author label and optional links */
+    readonly author?: EmbedAuthorInput
+    /** Footer label and optional icon */
+    readonly footer?: EmbedFooterInput
+    /** Full-size HTTP(S) image or attachment://filename for one same-message uploaded image or video */
+    readonly image?: EmbedMediaInput
+    /** Small HTTP(S) image or attachment://filename for one same-message uploaded image or video */
+    readonly thumbnail?: EmbedMediaInput
+    /** Up to 25 named sections, in display order. Entries are copied by index when the operation starts */
+    readonly fields?: readonly EmbedFieldInput[]
+}
+
+/**
+ * Label above the embed body, with optional links for its name and icon
+ *
+ * @category Messages
+ */
+export interface EmbedAuthorInput {
+    /** Required author name, 1–256 normalized UTF-16 code units */
+    readonly name: string
+    /** Destination for the author label */
+    readonly url?: string
+    /** HTTP(S) icon URL, at most 2048 characters. Attachment URLs are not accepted here */
+    readonly iconUrl?: string
+}
+
+/**
+ * Text beneath the embed body, with an optional icon
+ *
+ * @category Messages
+ */
+export interface EmbedFooterInput {
+    /** Required footer text, 1–2,048 normalized UTF-16 code units */
+    readonly text: string
+    /** HTTP(S) icon URL, at most 2048 characters. Attachment URLs are not accepted here */
+    readonly iconUrl?: string
+}
+
+/** Media for an image or thumbnail field in a rich card. Use an HTTP(S) image URL or attachment://filename for a new image or video uploaded with the same message.
+ * The SDK neither uploads through this object nor fetches remote or retained attachment bytes
+ *
+ * @category Messages
+ */
+export interface EmbedMediaInput {
+    /** Required HTTP(S) image URL or attachment://filename naming an uploaded image or video for image and thumbnail fields */
+    readonly url: string
+    /** Optional description for readers who cannot see the media, 1–4,096 normalized UTF-16 code units */
+    readonly description?: string
+}
+
+/**
+ * One heading and body pair within an embed, such as a Status field with value Passed
+ *
+ * @category Messages
+ */
+export interface EmbedFieldInput {
+    /** Required heading, 1–256 normalized UTF-16 code units */
+    readonly name: string
+    /** Required body, 0–1,024 normalized UTF-16 code units. An empty string is accepted */
+    readonly value: string
+    /** Request side-by-side display when space permits. Defaults to false */
+    readonly inline?: boolean
+}
+
+/**
+ * Author information received with a message. The object is frozen, missing or null server fields become omitted properties
+ *
+ * @category Messages
+ */
+export interface EmbedAuthor {
+    /** Server-provided label */
+    readonly name: string
+    /** Destination for the label */
+    readonly url?: string
+    /** Original icon URL */
+    readonly iconUrl?: string
+    /** Icon URL served through Fluxer's media proxy, when supplied */
+    readonly proxyIconUrl?: string
+}
+
+/**
+ * Preview-provider information received with a message, such as the site a link preview came from.
+ * Fluxer supplies only a name and a link, so unlike an author, a provider has no icon.
+ * The object is frozen, missing or null server fields become omitted properties
+ *
+ * @category Messages
+ */
+export interface EmbedProvider {
+    /** Server-provided label */
+    readonly name: string
+    /** Destination for the label */
+    readonly url?: string
+}
+
+/**
+ * Footer information received with a message. The object is frozen, missing or null server fields become omitted properties
+ *
+ * @category Messages
+ */
+export interface EmbedFooter {
+    /** Server-provided label */
+    readonly text: string
+    /** Original icon URL */
+    readonly iconUrl?: string
+    /** Icon URL served through Fluxer's media proxy, when supplied */
+    readonly proxyIconUrl?: string
+}
+
+/** Information about an embed image, video or audio file, not downloaded bytes.
+ * The object is frozen, missing or null server fields become omitted properties. Reading these fields does not download or play media
+ *
+ * @category Messages
+ */
+export interface EmbedMedia {
+    /** Original media location */
+    readonly url: string
+    /** Media URL served through Fluxer's media proxy, when supplied */
+    readonly proxyUrl?: string
+    /** Media type such as image/png, when known */
+    readonly contentType?: string
+    /** Server's identifier for the media contents. The SDK does not verify it against downloaded bytes */
+    readonly contentHash?: string
+    /** Width in pixels */
+    readonly width?: number
+    /** Height in pixels */
+    readonly height?: number
+    /** Alternative text when provided */
+    readonly description?: string
+    /** Base64 placeholder supplied by Fluxer, not decoded by the SDK */
+    readonly placeholder?: string
+    /** Duration in seconds */
+    readonly duration?: number
+    /** Numeric Fluxer media flags, kept as received, including flags unknown to this SDK */
+    readonly flags: number
+}
+
+/**
+ * A heading and body pair received within an embed. This object is frozen
+ *
+ * @category Messages
+ */
+export interface EmbedField {
+    /** Server-provided heading */
+    readonly name: string
+    /** Server-provided body */
+    readonly value: string
+    /** Whether inline display was requested */
+    readonly inline: boolean
+}
+
+/** One received card or link preview, without its optional child previews.
+ * This frozen object cannot be changed. Missing or null server fields are omitted.
+ * Use `EmbedInput` to send a card. A received card can include server-generated fields, but unknown fields are omitted
+ *
+ * @category Messages
+ */
+export interface EmbedChild {
+    /** Server-provided type, including types unknown to this SDK */
+    readonly type: string
+    /** Linked title */
+    readonly title?: string
+    /** Body text */
+    readonly description?: string
+    /** Destination URL */
+    readonly url?: string
+    /** Server-provided color integer */
+    readonly color?: number
+    /** Server-provided ISO timestamp string */
+    readonly timestamp?: string
+    /** Author metadata */
+    readonly author?: EmbedAuthor
+    /** Footer metadata */
+    readonly footer?: EmbedFooter
+    /** Full-size image metadata */
+    readonly image?: EmbedMedia
+    /** Thumbnail metadata */
+    readonly thumbnail?: EmbedMedia
+    /** Frozen named sections in received order */
+    readonly fields?: readonly EmbedField[]
+    /** Preview provider metadata */
+    readonly provider?: EmbedProvider
+    /** Video metadata, not a playable SDK resource */
+    readonly video?: EmbedMedia
+    /** Audio metadata, not a playable SDK resource */
+    readonly audio?: EmbedMedia
+    /** Preview HTML supplied by Fluxer. The SDK does not render or sanitize it. Treat it as untrusted when displaying it on a page */
+    readonly html?: string
+    /** Preferred HTML preview width in pixels */
+    readonly htmlWidth?: number
+    /** Preferred HTML preview height in pixels */
+    readonly htmlHeight?: number
+    /** Whether Fluxer marks the embed as NSFW */
+    readonly nsfw?: boolean
+}
+
+/** A rich card or generated link preview received with a message, including any child preview.
+ * This object is frozen, but later message observations may contain different media-processing results
+ *
+ * @category Messages
+ */
+export interface Embed extends EmbedChild {
+    /** At most one server-generated child, with no further nesting */
+    readonly children?: readonly EmbedChild[]
+}

package/src/error-tools.ts

@@ -0,0 +1,191 @@
+import * as Cause from "effect/Cause"
+import { FluxerlyError } from "./errors.js"
+import type { ApiErrorCode, ApiErrorDetail } from "./api-errors.js"
+import { errorInfo, errorText } from "#sdk/internal/logging"
+
+/**
+ * Settings for describeError
+ *
+ * @category Errors
+ */
+export interface DescribeErrorOptions {
+    /** Include stack frames for each error in the cause chain. Defaults to true.
+     * Consecutive frames inside the SDK and Effect collapse into one line, and expected SDK errors other than
+     * ConfigurationError and SdkDefect print no frames, because their stacks only show SDK internals
+     */
+    readonly stack?: boolean
+}
+
+/**
+ * Describe any error as readable multi-line text: Its name, SDK code, message, suggested fix, safe details and cause chain.
+ * Works for SDK errors, application errors, thrown non-Error values and Effect Causes, and never throws.
+ * A Cause is described reason by reason, as Failure, Defect or Interrupted, so pass exit.cause directly rather than
+ * squashing it first.
+ * Credential patterns, such as Authorization values, bare bot tokens, values assigned to keys ending in token or secret,
+ * token-shaped Bot or Bearer values, webhook URL tokens and the user information of a URL, such as user:password in
+ * https://user:password@host/path, are masked in names, application error codes, messages and stacks.
+ * A client's own configured token is masked only in that client's log records and failure reports.
+ * Use it to print a failed Result, an SdkDefect or a FailureReport's error
+ *
+ * @example
+ * ```ts
+ * import { createClient, describeError, orThrow } from "@neontechspace/fluxerly"
+ *
+ * try {
+ *     await using client = createClient({ token: process.env.FLUXER_BOT_TOKEN })
+ *     orThrow(await client.run())
+ * } catch (error) {
+ *     // Configuration errors, connection failures and SDK defects all print with their cause chain
+ *     console.error(describeError(error))
+ * }
+ * ```
+ *
+ * @category Errors
+ */
+export function describeError(error: unknown, options?: DescribeErrorOptions): string {
+    const stack = options?.stack !== false
+    let cause = false
+    try {
+        cause = Cause.isCause(error)
+    } catch {
+        // allow-silent: a proxy that rejects inspection is described as a plain value below
+    }
+    if (!cause) return describeOne(error, "", stack)
+    // Each reason of an Effect Cause is described in order, so a cleanup defect is not lost behind the first failure
+    const reasons = (error as Cause.Cause<unknown>).reasons.map((reason) =>
+        reason._tag === "Interrupt"
+            ? "Interrupted"
+            : reason._tag === "Fail"
+              ? `Failure:\n${describeOne(reason.error, "  ", stack)}`
+              : `Defect:\n${describeOne(reason.defect, "  ", stack)}`,
+    )
+    return reasons.length ? reasons.join("\n") : "Empty Cause with no failure, defect or interruption"
+}
+
+/** Describe one failure or defect value with masked text, indented for a Cause reason */
+function describeOne(error: unknown, indent: string, stack: boolean): string {
+    let sdk = false
+    try {
+        sdk = error instanceof FluxerlyError
+    } catch {
+        // allow-silent: a proxy that rejects prototype inspection is described as an application value below
+    }
+    return errorText(errorInfo(error, sdk ? "sdk" : "application"), indent, stack)
+}
+
+const retryableReasons = new Set(["busy", "network", "timeout", "rateLimit"])
+
+/** Whether repeating the same call is safe and may succeed. True for rate limits, full local capacity, and network
+ * failures and timeouts of reads or of writes that were not sent. False for rejections, invalid input, writes with an
+ * unknown outcome, cancellation and closed clients
+ */
+function isRetryable(error: unknown): boolean {
+    if (!(error instanceof FluxerlyError)) return false
+    switch (error._tag) {
+        case "RateLimitError":
+        case "ConnectionTimeoutError":
+            return true
+        case "ConnectionError":
+            return (error as unknown as { reason: string }).reason === "network"
+        case "ShardConnectionError":
+            return isRetryable(error.cause)
+    }
+    const fields = error as unknown as { reason?: unknown; outcome?: unknown }
+    if (typeof fields.reason !== "string" || !retryableReasons.has(fields.reason)) return false
+    const outcome = fields.outcome
+    // A read cannot have changed remote state, so an unknown outcome only matters for writes
+    return outcome !== "unknown" || fields.reason === "rateLimit" || error.details.read === true
+}
+
+/** Recognized Fluxer rejection category of an SDK operation error, or undefined for any other value */
+function apiCode(error: unknown): ApiErrorCode | undefined {
+    if (!(error instanceof FluxerlyError)) return undefined
+    const detail = (error as { readonly apiError?: ApiErrorDetail | null }).apiError
+    return detail?.code
+}
+
+/**
+ * Handlers for errors.match, keyed by each possible error's _tag, plus an optional _ fallback
+ *
+ * @category Errors
+ */
+export type ErrorMatchHandlers<E, R> = {
+    readonly [
+        K in E extends {
+            /** Discriminator of a tagged error */
+            readonly _tag: string
+        }
+            ? E["_tag"]
+            : never
+    ]?: (
+        error: Extract<
+            E,
+            {
+                /** Discriminator selecting this handler */
+                readonly _tag: K
+            }
+        >,
+    ) => R
+} & {
+    /** Called for any value without a matching handler, including non-SDK values */
+    readonly _?: (error: unknown) => R
+}
+
+/** Call the handler named by the error's _tag, or the _ fallback. Returns undefined when neither applies */
+function match<E, R>(error: E, handlers: ErrorMatchHandlers<E, R>): R | undefined {
+    const tag =
+        typeof error === "object" && error !== null && typeof (error as { _tag?: unknown })._tag === "string"
+            ? (error as unknown as { readonly _tag: string })._tag
+            : undefined
+    const handler =
+        tag !== undefined && tag !== "_" && Object.hasOwn(handlers, tag)
+            ? (handlers as Record<string, ((error: unknown) => R) | undefined>)[tag]
+            : undefined
+    if (handler) return handler(error)
+    return handlers._ ? handlers._(error) : undefined
+}
+
+/**
+ * Helpers for inspecting SDK errors in either entry point
+ *
+ * @category Errors
+ */
+export interface ErrorTools {
+    /** The recognized Fluxer rejection category of an operation error, such as `"missingPermissions"`, read from its
+     * apiError. Returns undefined for any other value, including cancellation, closed clients, invalid input and
+     * rejections Fluxer did not describe with a recognized code, so one condition works on every error of an operation's Result
+     */
+    readonly apiCode: (error: unknown) => ApiErrorCode | undefined
+    /** Whether repeating the same call is safe and may succeed, such as after a rate limit, full local capacity,
+     * or a network failure or timeout of a read or of a write that was not sent.
+     * A write whose outcome is unknown is not retryable, because Fluxer may already have applied it
+     */
+    readonly isRetryable: (error: unknown) => boolean
+    /** Call the handler named by the error's _tag, or the _ fallback, and return its result.
+     * Returns undefined when no handler applies
+     */
+    readonly match: <E, R>(error: E, handlers: ErrorMatchHandlers<E, R>) => R | undefined
+}
+
+/**
+ * Error helpers that classify and match errors through apiCode, isRetryable and match. To print an error, use describeError
+ *
+ * @example
+ * ```ts
+ * import { describeError, errors, type Client } from "@neontechspace/fluxerly"
+ *
+ * export async function sendWithOneRetry(client: Client, channelId: string) {
+ *     let sent = await client.messages.send(channelId, { content: "Hello" })
+ *     if (sent.isErr() && errors.isRetryable(sent.error)) sent = await client.messages.send(channelId, { content: "Hello" })
+ *     if (sent.isErr() && errors.apiCode(sent.error) === "missingPermissions") return console.warn("The bot cannot post here")
+ *     if (sent.isErr())
+ *         errors.match(sent.error, {
+ *             MessageError: (error) => console.warn("Send failed", error.reason),
+ *             _: (error) => console.error(describeError(error)),
+ *         })
+ * }
+ * ```
+ *
+ * @category Errors
+ */
+export const errors: ErrorTools = Object.freeze({ apiCode, isRetryable, match })