@neontechspace/fluxerly 1000.0.0-nightly.12

package/dist/api/effect/guilds.d.ts

@@ -0,0 +1,221 @@
+import type { CountOperationFailure, CountOperationOptions, GuildCountsResult } from "#sdk/counts";
+import type { GuildListQuery, GuildListSummary, GuildEdit, GuildVanityUrl, GuildVanityUrlUsage, Guild, GuildOperationFailure, GuildOperationOptions, ModerationOptions } from "#sdk/guilds";
+import type { GuildIterationQuery, PaginationError } from "#sdk/pagination";
+import type { OwnMessageDeletionOptions } from "#sdk/messages";
+import type * as Effect from "effect/Effect";
+import type * as Stream from "effect/Stream";
+/** Read or change guilds and obtain gateway counts.
+ * A guild is a Fluxer community. HTTP methods return Effects and do not require a gateway connection.
+ * The REST rules below exclude fetchCounts, which requires gateway readiness and has its own documented contract
+ *
+ * Requests share the client's REST or upload slots across all assigned shards, four per local shard by default, up to 64 (rest.concurrency).
+ * Attachment-download slots are separate, four by default (rest.mediaConcurrency).
+ * Both pools together allow 256 waiting requests or 4 MiB of queued JSON by default (rest.maxQueued and rest.queuedJsonMaxBytes)
+ *
+ * The total deadline defaults to the client's rest.defaultTimeoutMs, 30,000 ms unless configured, including waits. Reads retry transport failures and HTTP 500/502/503/504 at most twice.
+ * Retry delays are 125–250 ms, then 250–500 ms, or a longer valid Retry-After. Confirmed HTTP 429 waits are separate and never reset the deadline
+ *
+ * Input, 404, permission failures and malformed successes do not retry. Expected failures use GuildOperationError
+ *
+ * Successful REST JSON responses are limited to 16 MiB before parsing. This is not a total memory limit. Oversized responses fail with reason response and do not retry.
+ * If a response fails after a write was sent, the write may still have applied. The SDK does not assume rollback
+ *
+ * Interruption awaits owned cleanup. Closing clients use ClientClosedError. Defects retain Cause, including cleanup failures
+ *
+ * @category Guilds and members
+ */
+export interface Guilds {
+    /**
+     * Request fresh, visibility-filtered counts for 1–100 communities over the connected gateway.
+     * Use distinct positive decimal IDs without leading zeros, no greater than "9223372036854775807".
+     * The IDs are copied when execution starts.
+     * Every community must belong to a ready shard assigned to this client.
+     * An unassigned or unready shard fails with notConnected, not an omitted result.
+     * The result contains frozen counts and omittedGuildIds in requested order.
+     * An omitted entry is unavailable, not zero, and does not explain why it is missing.
+     * Community counts are separate observations, not one consistent snapshot.
+     * A missing whole reply fails with timeout
+     *
+     * One call uses one of four client-wide gateway request slots until all shard commands and replies finish.
+     * The channels.fetchMemberCounts and members.iterateChunks methods share those slots.
+     * There is no waiting queue for request slots, so excess calls fail with busy.
+     * Commands may wait for gateway pacing, and a full internal command queue also fails with busy.
+     * The default 30,000 ms deadline includes registration, commands and all reply fragments.
+     * Cancellation or deadline expiry withdraws unsent commands and immediately releases local request capacity.
+     * Fluxer also limits member and presence work, so a local slot does not guarantee a reply.
+     * Only a gateway gap on a participating shard fails with connectionLost, and late replies are ignored.
+     * No REST fallback, connection, caching, polling or retries are performed.
+     * Expected failures use CountOperationError or ClientClosedError
+     *
+     * @remarks
+     * The Effect uses the caller's services.
+     * Interruption waits for local cleanup but cannot cancel work already sent to Fluxer, and defects keep their Cause
+     *
+     * @example
+     * ```ts
+     * import { Effect } from "effect"
+     * import type { Client } from "@neontechspace/fluxerly/effect"
+     * export function countsExample(client: Client, guildId: string, channelId: string) {
+     *     return Effect.gen(function* () {
+     *         const guilds = yield* client.guilds.fetchCounts([guildId])
+     *         const channels = yield* client.channels.fetchMemberCounts(guildId, [channelId])
+     *         return { guilds, channels }
+     *     })
+     * }
+     * ```
+     */
+    fetchCounts(guildIds: readonly string[], options?: CountOperationOptions): Effect.Effect<GuildCountsResult, CountOperationFailure>;
+    /**
+     * Fetch one page of communities this bot belongs to, ordered by ascending guild ID.
+     * The limit option defaults to 200 and accepts 1–200.
+     * Choose either before or after, not both.
+     * Those cursors refer to existing memberships, and if a cursor community was removed, Fluxer may restart the page.
+     * The withCounts option defaults to false.
+     * Permission bits or requested approximate counts may be omitted, and an omitted value means unavailable, not zero.
+     * The frozen summaries do not read or populate the guild cache.
+     * No gateway connection or further page traversal is performed.
+     * Shared guild deadlines, retries and failures apply.
+     * This page is not a complete membership inventory or proof of matching gateway state
+     *
+     * @example
+     * ```ts
+     * import { Effect } from "effect"
+     * import type { Client } from "@neontechspace/fluxerly/effect"
+     * export const guildListExample = (client: Client) =>
+     *     client.guilds.fetchPage({ withCounts: true }).pipe(
+     *         Effect.map(page => page.map(({ id, permissions, approximateMemberCount }) => ({ id, permissions, approximateMemberCount }))),
+     *     )
+     * ```
+     */
+    fetchPage(query?: GuildListQuery, options?: GuildOperationOptions): Effect.Effect<readonly GuildListSummary[], GuildOperationFailure>;
+    /**
+     * Read the bot's community memberships in ascending ID order, retaining one page and never prefetching.
+     * The maxItems option is required.
+     * The pageSize option defaults to 200, maxPages defaults to 100, and timeoutMs applies to each page.
+     * Iteration ends at maxItems or an empty page, not a short page.
+     * A repeated or backward ID after a removed cursor fails with PaginationError cursorStalled before delivering that page.
+     * Other traversal failures are input and pageLimit, and remote failures keep fetchPage's error.
+     * Each consumption copies inputs independently.
+     * Client closure releases the page and fails the next pull.
+     * The withCounts option applies to every page, but missing permission bits or counts remain unavailable, not zero.
+     * No gateway connection or cache fill is needed.
+     * Already delivered communities remain with the caller, and separate pages do not guarantee a consistent inventory
+     *
+     * @remarks
+     * The returned Stream reads pages only while it is consumed.
+     * Failures end the Stream in its error channel.
+     * Interruption waits for request cleanup, and ending consumption releases the buffered page
+     *
+     * @example
+     * ```ts
+     * import type { Client } from "@neontechspace/fluxerly/effect"
+     * export function guildMembershipsExample(client: Client) {
+     *     return client.guilds.iterate({ maxItems: 1000 })
+     * }
+     * ```
+     */
+    iterate(query: GuildIterationQuery, options?: GuildOperationOptions): Stream.Stream<GuildListSummary, GuildOperationFailure | PaginationError>;
+    /**
+     * Remove this bot from one community while preserving its authored messages.
+     * HTTP 204 completes the removal, without waiting for a gateway event.
+     * The client remains usable for other communities
+     *
+     * Fluxer rejects owners or restricted memberships.
+     * Only confirmed HTTP 429 rejection retries.
+     * A lost response or cancellation can leave membership removed.
+     * Check fetch or the membership list to resolve an unknown outcome.
+     * Rejoining needs separate authorization
+     *
+     * Successful writes and writes with unknown outcomes invalidate cached guild resources and conflicting pending reads.
+     * A confirmed leave also forgets this client's selected member presences, while an unknown outcome keeps that selection.
+     * Any dispatched attempt clears channel and message caches, because messages need not identify their community.
+     * Objects already returned to the caller stay unchanged.
+     * This neither deletes the community nor shuts down the client
+     */
+    leave(guildId: string, options?: GuildOperationOptions): Effect.Effect<void, GuildOperationFailure>;
+    /**
+     * Irreversibly delete this bot's entire authored message history across one community.
+     * Use a decimal guild ID.
+     * Other authors' messages are preserved, and the bot stays in the community with the same roles
+     *
+     * Success follows Fluxer's empty HTTP 202 response, not a completed-job report, deletion count or gateway event.
+     * The community may still contain new or concurrent messages.
+     * Deletion can be partial and is not atomic.
+     * There is no recovery token or automatic reconciliation
+     *
+     * Bot credentials satisfy Fluxer's extra authentication checks, called sudo checks.
+     * No extra sudo fields or audit reason are accepted.
+     * Fluxer handles attachment removal without guaranteeing physical provider-storage or CDN erasure.
+     * The default deadline, rest.defaultTimeoutMs (30,000 ms unless configured), includes capacity and rate-limit waits.
+     * Only confirmed HTTP 429 rejection retries, and a 5xx or lost response never causes a replay.
+     * After dispatch, the entire enabled message cache is cleared and older pending reads cannot restore it.
+     * No gateway events are created locally.
+     * Cancellation or closure waits for request cleanup but cannot undo deletion.
+     * Options must include confirm: true. Without it, the call fails before any request with reason input and path options.confirm.
+     * Input, capacity and HTTP failures use GuildOperationError for guilds.deleteOwnMessages
+     *
+     * @example
+     * ```ts
+     * import type { Client } from "@neontechspace/fluxerly/effect"
+     * export const deleteOwnMessagesExample = (client: Client, channelId: string) =>
+     *     client.messages.deleteOwnMessages(channelId, { confirm: true })
+     * export const deleteOwnGuildMessagesExample = (client: Client, guildId: string) =>
+     *     client.guilds.deleteOwnMessages(guildId, { confirm: true })
+     * ```
+     */
+    deleteOwnMessages(guildId: string, options: OwnMessageDeletionOptions): Effect.Effect<void, GuildOperationFailure>;
+    /**
+     * Fetch a community's custom invite code, URL and use count with ManageGuild permission.
+     * A null code and URL means the community has no custom invite.
+     * The read is remote, without a vanity cache or gateway connection.
+     * Shared guild read retries, deadline, cancellation and failure rules apply
+     */
+    fetchVanityUrl(guildId: string, options?: GuildOperationOptions): Effect.Effect<GuildVanityUrlUsage, GuildOperationFailure>;
+    /**
+     * Set a community's custom invite code, replace it, or pass null to remove it.
+     * The code must already be lowercase, 2–32 ASCII letters or digits with single internal hyphens.
+     * No automatic normalization is performed
+     *
+     * ManageGuild is required.
+     * Setting a code also requires the community's VANITY_URL feature.
+     * Reserved or taken codes fail remotely.
+     * Changing a code releases the old code and starts a new use count, and reclaiming the old code is not guaranteed.
+     * Success returns the code and URL without a hidden use-count read, access check or gateway acknowledgement
+     *
+     * Shared guild deadlines and cleanup apply.
+     * Only confirmed HTTP 429 rejection retries, and dispatched writes invalidate guild snapshots.
+     * After an unknown outcome, call fetchVanityUrl before deciding how to recover.
+     * Provider-side partial changes may need operator recovery and are not rolled back automatically
+     */
+    editVanityUrl(guildId: string, code: string | null, options?: ModerationOptions): Effect.Effect<GuildVanityUrl, GuildOperationFailure>;
+    /**
+     * Change only supplied community settings that a bot may edit.
+     * Omitted fields remain unchanged, and no old settings are fetched or merged automatically
+     *
+     * ManageGuild is required.
+     * Fluxer checks feature restrictions and constraints beyond local GuildEdit validation.
+     * Success returns the server's observed configuration, not gateway acknowledgement.
+     * Shared guild write deadlines and cancellation cleanup apply.
+     * Dispatched writes invalidate cached guild data even when the outcome is unknown.
+     * After a lost response, fetch before deciding to retry.
+     * No rollback is guaranteed
+     */
+    edit(guildId: string, input: GuildEdit, options?: ModerationOptions): Effect.Effect<Guild, GuildOperationFailure>;
+    /**
+     * Look up a community in the enabled guild cache, without a request or gateway connection.
+     * The result is undefined when caching is disabled or the entry is absent, expired or evicted.
+     * Cached data may be stale, so use fetch for a remote read.
+     * 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
+     */
+    get(guildId: string): Effect.Effect<Guild | undefined>;
+    /**
+     * Fetch a community's identity and settings by decimal ID.
+     * Fluxer requires membership.
+     * The result is a frozen snapshot.
+     * This does not fetch or keep nested members, roles or channels, or infer counts or completeness
+     */
+    fetch(guildId: string, options?: GuildOperationOptions): Effect.Effect<Guild, GuildOperationFailure>;
+}
+//# sourceMappingURL=guilds.d.ts.map

package/dist/api/effect/guilds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guilds.d.ts","sourceRoot":"","sources":["../../../src/api/effect/guilds.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAClG,OAAO,KAAK,EACR,cAAc,EACd,gBAAgB,EAChB,SAAS,EACT,cAAc,EACd,mBAAmB,EACnB,KAAK,EACL,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACpB,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAA;AAC3E,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAA;AAC9D,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAA;AAC5C,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAA;AAE5C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,MAAM;IACnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACH,WAAW,CACP,QAAQ,EAAE,SAAS,MAAM,EAAE,EAC3B,OAAO,CAAC,EAAE,qBAAqB,GAChC,MAAM,CAAC,MAAM,CAAC,iBAAiB,EAAE,qBAAqB,CAAC,CAAA;IAC1D;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,SAAS,CACL,KAAK,CAAC,EAAE,cAAc,EACtB,OAAO,CAAC,EAAE,qBAAqB,GAChC,MAAM,CAAC,MAAM,CAAC,SAAS,gBAAgB,EAAE,EAAE,qBAAqB,CAAC,CAAA;IACpE;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,OAAO,CACH,KAAK,EAAE,mBAAmB,EAC1B,OAAO,CAAC,EAAE,qBAAqB,GAChC,MAAM,CAAC,MAAM,CAAC,gBAAgB,EAAE,qBAAqB,GAAG,eAAe,CAAC,CAAA;IAC3E;;;;;;;;;;;;;;;;OAgBG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,qBAAqB,CAAC,CAAA;IACnG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,yBAAyB,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,qBAAqB,CAAC,CAAA;IAClH;;;;;OAKG;IACH,cAAc,CACV,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,qBAAqB,GAChC,MAAM,CAAC,MAAM,CAAC,mBAAmB,EAAE,qBAAqB,CAAC,CAAA;IAC5D;;;;;;;;;;;;;;;OAeG;IACH,aAAa,CACT,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GAAG,IAAI,EACnB,OAAO,CAAC,EAAE,iBAAiB,GAC5B,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,qBAAqB,CAAC,CAAA;IACvD;;;;;;;;;;;OAWG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,qBAAqB,CAAC,CAAA;IACjH;;;;;;;OAOG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,GAAG,SAAS,CAAC,CAAA;IACtD;;;;;OAKG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,qBAAqB,CAAC,CAAA;CACvG"}

package/dist/api/effect/guilds.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=guilds.js.map

package/dist/api/effect/guilds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guilds.js","sourceRoot":"","sources":["../../../src/api/effect/guilds.ts"],"names":[],"mappings":""}

package/dist/api/effect/helpers.d.ts

@@ -0,0 +1,300 @@
+import { type AssetHelpers } from "#sdk/assets";
+import { type ColorInput, type RgbColor } from "#sdk/colors";
+import { type TextHelpers } from "#sdk/text";
+import { type CustomEmojiMarkup, type DisplayHelpers, type HelperError, type LinkHelpers, type Mention, type PermissionBitHelpers, type TimestampMarkup, type TimestampStyle } from "#sdk/helpers";
+import * as Effect from "effect/Effect";
+export type { AssetHelpers, LinkHelpers, PermissionBitHelpers, TextHelpers };
+/**
+ * Methods of the native format helper, which creates and reads mention, timestamp and custom-emoji markup and escapes Markdown.
+ * Most methods return plain values and throw HelperError for invalid input, and such a throw inside Effect code becomes a defect.
+ * The try-prefixed parsers accept untrusted text and return Effects that fail with HelperError in the error channel
+ *
+ * @category Builders and formatting
+ */
+export type FormatHelpers = Readonly<{
+    /**
+     * Add backslashes so text is treated literally by Fluxer's markup parser, for example escaping `**bold**`.
+     * Returns the escaped string immediately and never throws for string input.
+     * It does not change a message's `allowedMentions` or enable notifications
+     */
+    escapeMarkdown: (value: string) => string;
+    /**
+     * Create `<@id>` text for a decimal user ID, such as `<@123>`, and return it directly.
+     * Throws HelperError when the ID is not a valid decimal-string snowflake.
+     * This does not look up the user, and allowedMentions must be set separately to request a notification
+     */
+    userMention: (id: string) => string;
+    /**
+     * Create `<@&id>` text for a decimal role ID, such as `<@&123>`, and return it directly.
+     * Throws HelperError for an invalid ID.
+     * Role members are not notified merely because this text appears in a message, and allowedMentions must be set separately
+     */
+    roleMention: (id: string) => string;
+    /**
+     * Create `<#id>` text linking to a channel, such as `<#123>`, and return it directly.
+     * Throws HelperError for an invalid decimal-string ID, and no channel lookup occurs
+     */
+    channelMention: (id: string) => string;
+    /**
+     * Read a string containing exactly one user, role or channel mention into a frozen `{ kind, id }` object.
+     * Both `<@id>` and `<@!id>` produce kind `"user"`.
+     * Throws HelperError for surrounding text, malformed markup or an invalid decimal ID.
+     * For text received from users, use tryParseMention, which reports the same HelperError without throwing
+     */
+    parseMention: (value: string) => Mention;
+    /**
+     * Read a mention with the same rules as parseMention, but report invalid text without throwing.
+     * The default API returns a Result holding the frozen `{ kind, id }` object or HelperError.
+     * The native API returns an Effect that reads the text when run and fails with HelperError.
+     * Use it for text received from users or other untrusted sources
+     */
+    tryParseMention: (value: string) => Effect.Effect<Mention, HelperError, never>;
+    /**
+     * Create `<t:seconds:style>` message text from a Date, which Fluxer displays in the reader's local time.
+     * The style defaults to ShortDateTime, and milliseconds are dropped.
+     * The whole Unix second must be from 1 through 8_640_000_000_000.
+     * Throws HelperError for an invalid Date, a time outside that range or an unsupported style.
+     * The input Date is not changed
+     */
+    timestamp: (value: Date, style?: TimestampStyle) => string;
+    /**
+     * Read exactly one `<t:seconds:style>` or `<t:seconds>` string into a frozen object with a new Date and style.
+     * A missing style becomes ShortDateTime.
+     * The Date has whole-second precision.
+     * Throws HelperError for malformed markup, nonpositive seconds or dates outside JavaScript's range.
+     * For text received from users, use tryParseTimestamp, which reports the same HelperError without throwing
+     */
+    parseTimestamp: (value: string) => TimestampMarkup;
+    /**
+     * Read timestamp markup with the same rules as parseTimestamp, but report invalid text without throwing.
+     * The default API returns a Result holding the frozen date and style or HelperError.
+     * The native API returns an Effect that reads the text when run and fails with HelperError.
+     * Use it for text received from users or other untrusted sources
+     */
+    tryParseTimestamp: (value: string) => Effect.Effect<TimestampMarkup, HelperError, never>;
+    /**
+     * Create `<:name:id>` text, or `<a:name:id>` when animated is true.
+     * A GuildEmoji can be passed directly.
+     * Throws HelperError for invalid names, IDs or animation values.
+     * This does not upload or look up an emoji
+     */
+    customEmoji: (input: CustomEmojiMarkup) => string;
+    /**
+     * Read exactly one `<:name:id>` or `<a:name:id>` string into frozen name, ID and animated fields.
+     * Throws HelperError for malformed markup.
+     * This does not resolve shortcodes such as `:smile:` or parse Unicode emoji.
+     * For text received from users, use tryParseCustomEmoji, which reports the same HelperError without throwing
+     */
+    parseCustomEmoji: (value: string) => CustomEmojiMarkup;
+    /**
+     * Read custom-emoji markup with the same rules as parseCustomEmoji, but report invalid text without throwing.
+     * The default API returns a Result holding the frozen name, ID and animated fields or HelperError.
+     * The native API returns an Effect that reads the text when run and fails with HelperError.
+     * Use it for text received from users or other untrusted sources
+     */
+    tryParseCustomEmoji: (value: string) => Effect.Effect<CustomEmojiMarkup, HelperError, never>;
+}>;
+/**
+ * Create and read Fluxer mention, timestamp and custom-emoji markup without a client or network requests.
+ * Most methods return plain values immediately, the same as in the default API, and throw HelperError for invalid input.
+ * Inside Effect code such a throw becomes a defect rather than a typed failure, because invalid input is a programming mistake.
+ * For text received from users, tryParseMention, tryParseTimestamp and tryParseCustomEmoji return Effects that read the text when run and fail with HelperError.
+ * Mention markup alone does not enable notifications
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { format, links, type GuildChannel } from "@neontechspace/fluxerly/effect"
+ *
+ * export const helpersEffectExample = (userId: string, messageId: string, channel: GuildChannel, userText: string) =>
+ *     Effect.gen(function* () {
+ *         const mentioned = yield* format.tryParseMention(userText)
+ *         return {
+ *             escaped: format.escapeMarkdown("@everyone: **literal**"),
+ *             mention: format.userMention(userId),
+ *             message: links.message({ id: messageId, channelId: channel.id }, channel),
+ *             mentionedId: mentioned.id,
+ *         }
+ *     })
+ * ```
+ *
+ * @category Builders and formatting
+ */
+export declare const format: FormatHelpers;
+/**
+ * Methods of the native snowflakes helper, which reads and converts decimal Fluxer IDs without losing precision.
+ * Conversions return plain values and throw HelperError for invalid input, and such a throw inside Effect code becomes a defect.
+ * The tryParse method returns an Effect that fails with HelperError in the error channel
+ *
+ * @category Builders and formatting
+ */
+export type SnowflakeHelpers = Readonly<{
+    /**
+     * Return true for a decimal string from `"0"` through `"9223372036854775807"`, with no extra leading zeroes.
+     * Returns false immediately for numbers, whitespace and invalid strings, without converting through Number or failing
+     */
+    isValid: (value: unknown) => value is string;
+    /**
+     * Convert a valid decimal-string ID to bigint without losing precision.
+     * Throws HelperError for an invalid ID.
+     * For IDs received from users, use tryParse, which reports the same HelperError without throwing
+     */
+    parse: (value: string) => bigint;
+    /**
+     * Convert a decimal-string ID with the same rules as parse, but report an invalid ID without throwing.
+     * The default API returns a Result holding the bigint or HelperError.
+     * The native API returns an Effect that reads the ID when run and fails with HelperError.
+     * Use it for IDs received from users or other untrusted sources
+     */
+    tryParse: (value: string) => Effect.Effect<bigint, HelperError, never>;
+    /**
+     * Return a new UTC Date for the creation time encoded in an ID.
+     * Throws HelperError for an invalid ID.
+     * This decodes the ID's high 41 timestamp bits relative to 2015-01-01 UTC, and does not fetch the resource or prove it is visible
+     */
+    createdAt: (value: string) => Date;
+    /**
+     * Make the smallest ID for a Date's exact UTC millisecond, useful as a time-based pagination boundary.
+     * Throws HelperError for an invalid Date, a date before 2015-01-01 UTC or a result outside the ID range.
+     * This does not create a resource.
+     * Whether the boundary is included depends on the endpoint using it
+     */
+    boundary: (value: Date) => string;
+    /**
+     * Return the shard that receives a community's gateway events when the bot runs totalShards shards.
+     * Fluxer calls a community a guild, so the first argument is a guild ID.
+     * Fluxer routes each community with (guildId >> 22) % totalShards, and this helper applies the same formula.
+     * Use it to find which process owns a community when shards run in several processes.
+     * Throws HelperError for an invalid ID or a totalShards outside 1 through 16,384.
+     * It does not check whether the bot belongs to that community
+     */
+    shardFor: (guildId: string, totalShards: number) => number;
+}>;
+/** Validate Fluxer IDs, read their creation time or create pagination boundaries.
+ * A snowflake is Fluxer's time-based decimal-string ID. Conversions use bigint to avoid Number precision loss.
+ * They return plain values and throw HelperError for invalid input, which becomes a defect inside Effect code.
+ * For IDs received from users, tryParse returns an Effect that fails with HelperError instead
+ *
+ * @category Builders and formatting
+ */
+export declare const snowflakes: SnowflakeHelpers;
+/** Choose a display name from user data and an optional community member, without a request or cache lookup.
+ * The display.name helper prefers the member nickname, then the user's displayName, then username.
+ * Only null or undefined trigger a fallback.
+ * Supply a member belonging to the same user, because this helper does not check identity
+ *
+ * @category Builders and formatting
+ */
+export declare const display: DisplayHelpers;
+/** Build and inspect permission bitfields from named Fluxer permissions.
+ * A bitfield stores permission flags in a bigint. Methods return plain values immediately, the same as in the default API, without fetching resources or deciding whether an action is allowed.
+ * Unknown names or bits outside the unsigned 64-bit range throw HelperError, and such a throw inside Effect code becomes a defect
+ *
+ * @category Roles and permissions
+ */
+export declare const permissionBits: PermissionBitHelpers;
+/**
+ * Methods of the native colors helper, which converts RGB numbers, hex strings and tuples.
+ * Most methods return plain values and throw HelperError for invalid input, and such a throw inside Effect code becomes a defect.
+ * The tryParse method returns an Effect that fails with HelperError in the error channel
+ *
+ * @category Builders and formatting
+ */
+export type ColorHelpers = Readonly<{
+    /**
+     * Convert a six-digit hexadecimal string, an RGB array of three integer channels from 0 through 255, or a color number to the integer used by embeds and roles.
+     * The leading `#` is optional.
+     * CSS names, three-digit shorthand, alpha channels and surrounding whitespace are rejected.
+     * Values are never rounded or clamped, and invalid input throws HelperError.
+     * For colors received from users, use tryParse, which reports the same HelperError without throwing
+     */
+    parse: (value: ColorInput) => number;
+    /**
+     * Convert a color with the same rules as parse, but report invalid input without throwing.
+     * The default API returns a Result holding the color integer or HelperError.
+     * The native API returns an Effect that reads the input when run and fails with HelperError.
+     * Use it for colors received from users or other untrusted sources
+     */
+    tryParse: (value: ColorInput) => Effect.Effect<number, HelperError, never>;
+    /**
+     * Turn a color integer into a lowercase six-digit string such as `"#000001"`, including leading zeroes.
+     * Accepts only integers from 0 through 0xffffff, not the strings or arrays accepted by `parse`.
+     * Throws HelperError for invalid numbers
+     */
+    toHex: (value: number) => string;
+    /**
+     * Split a color integer into a new frozen `[red, green, blue]` array, each from 0 through 255.
+     * Accepts only integers from 0 through 0xffffff.
+     * Throws HelperError for invalid numbers
+     */
+    toRgb: (value: number) => RgbColor;
+}>;
+/** Convert RGB colors between integers, hex strings and channel tuples.
+ * Methods return plain values immediately. Invalid values throw HelperError instead of being coerced or clamped, and CSS color names are not accepted.
+ * Such a throw inside Effect code becomes a defect. For colors received from users, tryParse returns an Effect that fails with HelperError instead
+ *
+ * @category Builders and formatting
+ */
+export declare const colors: ColorHelpers;
+/**
+ * Split long text into length-bounded pieces without losing its contents.
+ * The caller chooses the length limit, how to send the pieces and any Markdown handling.
+ * The split method returns the pieces directly, without sending them.
+ * Invalid text or options throw HelperError, and such a throw inside Effect code becomes a defect
+ *
+ * @example
+ * ```ts
+ * import { Effect } from "effect"
+ * import { permissionBits, colors, text } from "@neontechspace/fluxerly/effect"
+ *
+ * export function pureHelpersExample(bits: bigint, content: string, colorText: string) {
+ *     return Effect.gen(function* () {
+ *         const color = yield* colors.tryParse(colorText)
+ *         return {
+ *             required: permissionBits.from(["ManageRoles", "ManageMessages"]),
+ *             missing: permissionBits.missing(bits, ["ManageRoles", "ManageMessages"]),
+ *             inspection: permissionBits.inspect(bits),
+ *             color,
+ *             chunks: text.split(content, { maxLength: 2_000 }),
+ *         }
+ *     })
+ * }
+ * ```
+ *
+ * @category Builders and formatting
+ */
+export declare const text: TextHelpers;
+/** Build hosted Fluxer channel, message and bot-installation links from supplied IDs.
+ * Methods return URLs immediately, the same as in the default API, and throw HelperError for invalid input.
+ * Such a throw inside Effect code becomes a defect. Building a link does not visit it or check access
+ *
+ * @category Builders and formatting
+ */
+export declare const links: LinkHelpers;
+/**
+ * Build image URLs for hosted Fluxer from supplied user, member, community, emoji or sticker data.
+ * Methods return URLs immediately, the same as in the default API, and use fixed hosted addresses. Use client.instance.resolve for URLs on a selected self-hosted instance.
+ * Invalid targets, IDs, hashes or options throw AssetUrlError, and such a throw inside Effect code becomes a defect.
+ * Image format defaults to WebP. Omit size to leave pixel size selection to Fluxer.
+ * Options are validated even when the supplied asset is absent.
+ * These helpers do not fetch profiles, change caches, download bytes, refresh URLs or change attachment or embed URLs.
+ * Custom base addresses are not accepted by this hosted namespace.
+ * Omitted optional asset hashes become `undefined`. Known absent hashes become `null`. A returned URL does not prove the asset exists
+ *
+ * @example
+ * ```ts
+ * import { assets, AssetFormats, type Guild, type GuildEmoji, type GuildMember, type User, type UserProfile } from "@neontechspace/fluxerly/effect"
+ *
+ * export const assetsEffectExample = (user: Pick<User, "id" | "avatar">, member: Pick<GuildMember, "guildId" | "userId" | "avatar" | "profileFlags">, guild: Pick<Guild, "id" | "icon">, emoji: Pick<GuildEmoji, "id" | "animated">, profile: UserProfile) => ({
+ *     avatar: assets.displayAvatar(user, { size: 256, format: AssetFormats.Webp }),
+ *     memberAvatar: assets.displayMemberAvatar(user, member, { size: 256 }),
+ *     icon: assets.guildIcon(guild, { format: AssetFormats.Png }),
+ *     emojiUrl: assets.emoji(emoji, { animated: emoji.animated }),
+ *     banner: assets.userBanner(profile),
+ * })
+ * ```
+ *
+ * @category Builders and formatting
+ */
+export declare const assets: AssetHelpers;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/api/effect/helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../../src/api/effect/helpers.ts"],"names":[],"mappings":"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"}