@neontechspace/fluxerly 1000.0.0-nightly.12

package/dist/observer.d.ts

@@ -0,0 +1,111 @@
+import type { EventName } from "./events.js";
+/**
+ * One finished REST request attempt. A retried request reports each attempt separately
+ *
+ * @category Logging and diagnostics
+ */
+export interface RestObservation {
+    /** Discriminator for a finished REST request attempt */
+    readonly type: "rest";
+    /** HTTP method, such as GET or POST */
+    readonly method: string;
+    /** Route template with IDs replaced by placeholders, such as /channels/:id/messages */
+    readonly route: string;
+    /** HTTP status of the response, or null when no response arrived, such as after a network failure or timeout */
+    readonly status: number | null;
+    /** Milliseconds from sending the request until its response headers arrived or it failed */
+    readonly durationMs: number;
+    /** One-based attempt number. Values above 1 are automatic retries of the same request */
+    readonly attempt: number;
+}
+/**
+ * A REST request that waits before retrying because Fluxer rate-limited it with HTTP 429
+ *
+ * @category Logging and diagnostics
+ */
+export interface RateLimitObservation {
+    /** Discriminator for a rate-limit wait */
+    readonly type: "rateLimit";
+    /** HTTP method of the waiting request */
+    readonly method: string;
+    /** Route template of the waiting request, with IDs replaced by placeholders */
+    readonly route: string;
+    /** Milliseconds the request waits before its retry */
+    readonly waitMs: number;
+    /** Whether the limit pauses every API route of this client rather than one rate-limit group */
+    readonly global: boolean;
+}
+/**
+ * A shard begins a reconnection attempt after its established connection was lost
+ *
+ * @category Logging and diagnostics
+ */
+export interface ReconnectObservation {
+    /** Discriminator for a reconnection attempt */
+    readonly type: "reconnect";
+    /** Local shard that reconnects */
+    readonly shardId: number;
+}
+/**
+ * A shard resumed its session, so Fluxer replays the events it missed
+ *
+ * @category Logging and diagnostics
+ */
+export interface ResumeObservation {
+    /** Discriminator for a resumed session */
+    readonly type: "resume";
+    /** Local shard that resumed */
+    readonly shardId: number;
+    /** Milliseconds the shard was offline, when it was connected before in this process */
+    readonly outageMs?: number;
+}
+/**
+ * One finished event handler or prefix command router invocation, including event and command middleware.
+ * A router emits one observation for every handled message, even when it matches no command
+ *
+ * @category Logging and diagnostics
+ */
+export interface HandlerObservation {
+    /** Discriminator for a finished handler invocation */
+    readonly type: "handler";
+    /** Event the handler received, such as messageCreate */
+    readonly event: EventName;
+    /** Canonical prefix command name when the router matched one, including denied or middleware-stopped commands. Absent when no command matched */
+    readonly command?: string;
+    /** Identifier of the subscription that ran the handler, such as messageCreate#3 */
+    readonly subscriptionId: string;
+    /** Local shard that received the event */
+    readonly shardId: number;
+    /** Milliseconds from the start of the invocation until it finished */
+    readonly durationMs: number;
+    /**
+     * How the invocation ended. The value success means it finished without a reported failure, including a command
+     * denial or no command match. The value failure means a handler, command or middleware failure was reported to
+     * onError or the log, even when middleware recovered from it. The value cancelled means interruption stopped the
+     * invocation, such as shutdown or closing the subscription, and takes precedence over an earlier reported failure
+     */
+    readonly outcome: "success" | "failure" | "cancelled";
+    /** Name of the failure's error, such as TypeError, for a failed invocation */
+    readonly errorName?: string;
+    /** Stable code of the failure's error, when it has one */
+    readonly errorCode?: string;
+}
+/**
+ * One structured measurement passed to the observe client option. Use the type field to tell them apart
+ *
+ * @category Logging and diagnostics
+ */
+export type Observation = RestObservation | RateLimitObservation | ReconnectObservation | ResumeObservation | HandlerObservation;
+/**
+ * Receive structured measurements of this client's work, such as REST request durations, rate-limit waits,
+ * reconnection attempts, resumed sessions and handler durations, to export as metrics or traces to any monitoring system.
+ * Each observation is a frozen object with plain values. Route templates replace IDs with placeholders, and observations
+ * never contain tokens, payloads or message content.
+ * The SDK calls the observer synchronously when the measured work finishes, so keep it short and move slow work, such as
+ * network export, elsewhere. Return values are ignored and promises are not awaited. A thrown error or rejected promise
+ * is counted in diagnostics().counters.sinkFailures and reported once on standard error, without changing SDK work
+ *
+ * @category Logging and diagnostics
+ */
+export type Observer = (observation: Observation) => void;
+//# sourceMappingURL=observer.d.ts.map

package/dist/observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.d.ts","sourceRoot":"","sources":["../src/observer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC5B,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,uCAAuC;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,uFAAuF;IACvF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,gHAAgH;IAChH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,4FAA4F;IAC5F,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACjC,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,yCAAyC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,+EAA+E;IAC/E,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,+FAA+F;IAC/F,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACjC,+CAA+C;IAC/C,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,kCAAkC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAC9B,0CAA0C;IAC1C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,+BAA+B;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IAC/B,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,iJAAiJ;IACjJ,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,mFAAmF;IACnF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;IAC/B,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,sEAAsE;IACtE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,WAAW,CAAA;IACrD,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED;;;;GAIG;AACH,MAAM,MAAM,WAAW,GACnB,eAAe,GAAG,oBAAoB,GAAG,oBAAoB,GAAG,iBAAiB,GAAG,kBAAkB,CAAA;AAE1G;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,WAAW,EAAE,WAAW,KAAK,IAAI,CAAA"}

package/dist/observer.js

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

package/dist/observer.js.map

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

package/dist/pagination.d.ts

@@ -0,0 +1,117 @@
+import { FluxerlyError } from "./errors.js";
+import { type InputValidationDetail } from "./input-validation.js";
+/** Read a Fluxer list one page at a time through an iterator or Effect Stream. Set item and page limits.
+ * Set maxItems to limit the number of delivered items. The SDK requests the next page only after the current one is consumed
+ *
+ * Each consumption of the iterator or Stream starts independently and copies the inputs then, not at creation
+ *
+ * Early exit, failure, interruption and client shutdown release that consumption's buffered page and tracking state.
+ * Already-delivered items remain with the caller
+ *
+ * The SDK does not fetch ahead, persist results or remove duplicates across separate consumptions
+ *
+ * Each page uses its own request deadline. The item and page caps do not provide a total elapsed-time deadline.
+ * Changes on Fluxer during traversal can cause the pages to differ from a single complete snapshot
+ *
+ * @category Options
+ */
+export interface PaginationQuery {
+    /** Maximum items to deliver, a required positive safe integer. Reaching this cap finishes normally, without proving remote exhaustion */
+    readonly maxItems: number;
+    /** Maximum items to request per page, reduced when fewer items remain under maxItems.
+     * History defaults to 50 with a range of 1 through 100, members to 100 with 1 through 1,000.
+     * Community memberships default to 200 with 1 through 200, reaction users to 25 with 1 through 100.
+     * Pins default to 50 with 1 through 50, audit logs to 50 with 1 through 100.
+     * Member search defaults to 100 with 1 through 100, message search to 25 with 1 through 25
+     */
+    readonly pageSize?: number;
+    /** Maximum page requests, a positive safe integer, default 100.
+     * Retrying a request for the same page does not use another page allowance. Duplicate-only pin pages do count.
+     * Needing a further page after this allowance fails with PaginationError reason pageLimit, preserving already-delivered items
+     */
+    readonly maxPages?: number;
+}
+/** Limits and starting point for messages.iterateHistory, reading newest messages first.
+ * For newer-than or centered windows, use messages.fetchHistory with after or around instead
+ *
+ * @category Messages
+ */
+export interface HistoryIterationQuery extends PaginationQuery {
+    /** Start with messages older than this decimal message ID, excluding it. Omit to start with the latest visible messages */
+    readonly before?: string;
+}
+/** Limits and starting point for ascending member or reaction-user traversal.
+ * Ordering follows user IDs, not join dates or reaction times
+ *
+ * @category Guilds and members
+ */
+export interface UserIterationQuery extends PaginationQuery {
+    /** Start with decimal user IDs greater than this ID, excluding it. Omit to start from the first page */
+    readonly after?: string;
+}
+/**
+ * Limits and starting point for guilds.iterate, reading the bot's community memberships in ascending community-ID order
+ *
+ * @category Guilds and members
+ */
+export interface GuildIterationQuery extends PaginationQuery {
+    /** Start after this decimal community ID, excluding it. Omit for the first page.
+     * Repeated results caused by a removed cursor fail with PaginationError reason cursorStalled
+     */
+    readonly after?: string;
+    /** Ask Fluxer to include approximate member and presence counts on each page, default false.
+     * Counts and permissions can still be omitted. An omitted summary field remains unavailable, not zero
+     */
+    readonly withCounts?: boolean;
+}
+/** Limits and starting point for messages.iteratePins, reading newest pin times first.
+ * Each message ID is delivered at most once per consumption. Its first observed pin wins, even if it is later repinned.
+ * Timestamp ties or concurrent changes can prevent complete enumeration.
+ * If the next timestamp does not become older, traversal fails with cursorStalled after delivering newly observed IDs from that page
+ *
+ * @category Messages
+ */
+export interface PinIterationQuery extends PaginationQuery {
+    /** Start with older pin times than this ISO 8601 timestamp with a timezone. Omit to use Fluxer's current-time default */
+    readonly before?: string;
+}
+/**
+ * Operation name included in a PaginationError or default-API SDK defect to identify the traversal
+ *
+ * @category Errors
+ */
+export type PaginationOperation = "iterateHistory" | "messages.iterateSearch" | "members.iterate" | "guilds.iterate" | "members.iterateSearch" | "iterateReactionUsers" | "iteratePins" | "auditLogs.iterate" | "threads.iterateMembers";
+/** Reading multiple pages failed because of invalid settings, a page limit, a stalled cursor or search readiness.
+ * Contains no resource IDs, response bodies or accumulated partial result.
+ * Items returned before the failure remain available to the application. A remote request failure keeps the underlying page-operation error instead of becoming PaginationError.
+ * Default-API cancellation uses CancelledError, while native interruption stays in Effect Cause. Unexpected defects remain separate
+ *
+ * @category Errors
+ */
+export declare class PaginationError extends FluxerlyError {
+    /** Literal error tag for identifying PaginationError */
+    readonly _tag = "PaginationError";
+    /** Frozen local validation detail for reason input, otherwise null */
+    readonly inputValidation: InputValidationDetail | null;
+    /** Traversal that failed. Its presence does not establish that any page request was sent */
+    readonly operation: PaginationOperation;
+    /** Failure category.
+     * The reason input means invalid settings, cursorStalled means no cursor progress, and pageLimit means another page would exceed maxPages.
+     * The reason indexing means message search is preparing an index and traversal will not poll it
+     */
+    readonly reason: "input" | "cursorStalled" | "pageLimit" | "indexing";
+    /** Identify the failed traversal and its local failure reason.
+     * Validation detail is copied and frozen when supplied, otherwise null. Construction does not start or resume traversal
+     */
+    constructor(options: {
+        /** Traversal that failed */
+        readonly operation: PaginationOperation;
+        /** Failure category, as described on the reason field */
+        readonly reason: PaginationError["reason"];
+        /** Safe local validation detail copied into inputValidation. Defaults to null */
+        readonly inputValidation?: InputValidationDetail | null | undefined;
+        /** Underlying failure retained as the error's cause */
+        readonly cause?: unknown;
+    });
+}
+//# sourceMappingURL=pagination.d.ts.map

package/dist/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAoB,MAAM,aAAa,CAAA;AAE7D,OAAO,EAA+B,KAAK,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAE/F;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,eAAe;IAC5B,yIAAyI;IACzI,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAsB,SAAQ,eAAe;IAC1D,2HAA2H;IAC3H,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAmB,SAAQ,eAAe;IACvD,wGAAwG;IACxG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAoB,SAAQ,eAAe;IACxD;;OAEG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAChC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAkB,SAAQ,eAAe;IACtD,yHAAyH;IACzH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED;;;;GAIG;AACH,MAAM,MAAM,mBAAmB,GACzB,gBAAgB,GAChB,wBAAwB,GACxB,iBAAiB,GACjB,gBAAgB,GAChB,uBAAuB,GACvB,sBAAsB,GACtB,aAAa,GACb,mBAAmB,GACnB,wBAAwB,CAAA;AAiB9B;;;;;;GAMG;AACH,qBAAa,eAAgB,SAAQ,aAAa;IAC9C,wDAAwD;IACxD,QAAQ,CAAC,IAAI,qBAAoB;IACjC,sEAAsE;IACtE,QAAQ,CAAC,eAAe,EAAE,qBAAqB,GAAG,IAAI,CAAA;IACtD,4FAA4F;IAC5F,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAA;IACvC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,eAAe,GAAG,WAAW,GAAG,UAAU,CAAA;IACrE;;OAEG;IACH,YAAY,OAAO,EAAE;QACjB,4BAA4B;QAC5B,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAA;QACvC,yDAAyD;QACzD,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,CAAA;QAC1C,iFAAiF;QACjF,QAAQ,CAAC,eAAe,CAAC,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,CAAA;QACnE,uDAAuD;QACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAC3B,EAwBA;CACJ"}

package/dist/pagination.js

@@ -0,0 +1,61 @@
+import { FluxerlyError, operationDetails } from "./errors.js";
+import { operationErrorMessage, operationFailureHint } from "./api-errors.js";
+import { freezeInputValidationDetail } from "./input-validation.js";
+/** What each non-input pagination failure means, for the error message */
+const paginationExplanations = {
+    input: "The iteration settings are invalid",
+    cursorStalled: "The next page did not move past the previous one, so iteration stopped to avoid repeating items",
+    pageLimit: "Reading another page would exceed maxPages",
+    indexing: "Fluxer is still building the search index, so iteration stopped without polling",
+};
+/** Suggested next step for each non-input pagination failure */
+const paginationHints = {
+    cursorStalled: "Retry later, because concurrent changes or equal timestamps can repeat a cursor",
+    pageLimit: "Raise maxPages, or lower maxItems or raise pageSize so fewer pages are needed",
+    indexing: "Retry the search after a short wait",
+};
+/** Reading multiple pages failed because of invalid settings, a page limit, a stalled cursor or search readiness.
+ * Contains no resource IDs, response bodies or accumulated partial result.
+ * Items returned before the failure remain available to the application. A remote request failure keeps the underlying page-operation error instead of becoming PaginationError.
+ * Default-API cancellation uses CancelledError, while native interruption stays in Effect Cause. Unexpected defects remain separate
+ *
+ * @category Errors
+ */
+export class PaginationError extends FluxerlyError {
+    /** Literal error tag for identifying PaginationError */
+    _tag = "PaginationError";
+    /** Frozen local validation detail for reason input, otherwise null */
+    inputValidation;
+    /** Traversal that failed. Its presence does not establish that any page request was sent */
+    operation;
+    /** Failure category.
+     * The reason input means invalid settings, cursorStalled means no cursor progress, and pageLimit means another page would exceed maxPages.
+     * The reason indexing means message search is preparing an index and traversal will not poll it
+     */
+    reason;
+    /** Identify the failed traversal and its local failure reason.
+     * Validation detail is copied and frozen when supplied, otherwise null. Construction does not start or resume traversal
+     */
+    constructor(options) {
+        const { operation, reason, inputValidation = null } = options;
+        super(operationErrorMessage({
+            subject: "Pagination",
+            operation,
+            reason,
+            outcome: "notDispatched",
+            inputExplanation: inputValidation?.explanation ?? paginationExplanations[reason],
+        }), {
+            code: `pagination.${reason}`,
+            hint: reason === "input"
+                ? operationFailureHint({ reason, outcome: "notDispatched", inputPath: inputValidation?.path })
+                : paginationHints[reason],
+            cause: options.cause,
+            details: operationDetails({ operation, reason }),
+        });
+        this.name = this._tag;
+        this.inputValidation = freezeInputValidationDetail(inputValidation);
+        this.operation = operation;
+        this.reason = reason;
+    }
+}
+//# sourceMappingURL=pagination.js.map

package/dist/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../src/pagination.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC7D,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAC7E,OAAO,EAAE,2BAA2B,EAA8B,MAAM,uBAAuB,CAAA;AAkG/F,0EAA0E;AAC1E,MAAM,sBAAsB,GAAwD;IAChF,KAAK,EAAE,oCAAoC;IAC3C,aAAa,EAAE,iGAAiG;IAChH,SAAS,EAAE,4CAA4C;IACvD,QAAQ,EAAE,iFAAiF;CAC9F,CAAA;AAED,gEAAgE;AAChE,MAAM,eAAe,GAA0E;IAC3F,aAAa,EAAE,iFAAiF;IAChG,SAAS,EAAE,+EAA+E;IAC1F,QAAQ,EAAE,qCAAqC;CAClD,CAAA;AAED;;;;;;GAMG;AACH,MAAM,OAAO,eAAgB,SAAQ,aAAa;IAC9C,wDAAwD;IAC/C,IAAI,GAAG,iBAAiB,CAAA;IACjC,sEAAsE;IAC7D,eAAe,CAA8B;IACtD,4FAA4F;IACnF,SAAS,CAAqB;IACvC;;;OAGG;IACM,MAAM,CAAsD;IACrE;;OAEG;IACH,YAAY,OASX;QACG,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,EAAE,GAAG,OAAO,CAAA;QAC7D,KAAK,CACD,qBAAqB,CAAC;YAClB,OAAO,EAAE,YAAY;YACrB,SAAS;YACT,MAAM;YACN,OAAO,EAAE,eAAe;YACxB,gBAAgB,EAAE,eAAe,EAAE,WAAW,IAAI,sBAAsB,CAAC,MAAM,CAAC;SACnF,CAAC,EACF;YACI,IAAI,EAAE,cAAc,MAAM,EAAE;YAC5B,IAAI,EACA,MAAM,KAAK,OAAO;gBACd,CAAC,CAAC,oBAAoB,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC;gBAC9F,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC;YACjC,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,OAAO,EAAE,gBAAgB,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;SACnD,CACJ,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAA;QACrB,IAAI,CAAC,eAAe,GAAG,2BAA2B,CAAC,eAAe,CAAC,CAAA;QACnE,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;QAC1B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACxB,CAAC;CACJ"}

package/dist/permissions.d.ts

@@ -0,0 +1,73 @@
+import type { GuildChannel } from "./channels.js";
+import type { Guild, GuildMember, GuildRole, MemberReference } from "./guilds.js";
+/**
+ * Calculate a member's community or channel permission bits from supplied guild, member, role and channel data
+ *
+ * The `roles` list must include the implicit everyone role whose ID equals `guild.id` and every role in `member.roleIds`.
+ * Supply `channel` with permissionOverwrites to include that channel's explicit permission overrides.
+ * Omit `channel` to calculate community-level bits.
+ * For a thread, supply the thread as `channel` and its parent channel, with its overwrites, as `parentChannel`
+ *
+ * The calculation first combines everyone and assigned-role grants.
+ * It then applies channel overrides for everyone, the member's roles together, and finally the member.
+ * Allows win over denies within each stage.
+ * Owners and members with Administrator receive all 64 bits, including unknown bits.
+ * A thread has no overwrites of its own, so Fluxer calculates in its parent channel and then grants SendMessages
+ * exactly when SendMessagesInThreads is granted there. The calculation does the same
+ *
+ * Duplicate, incomplete or cross-community resources fail with GuildOperationError reason input
+ *
+ * The calculated bits do not prove that Fluxer will allow an action.
+ * The calculation does not check visibility, timeouts, role hierarchy, multi-factor authentication (MFA) or age gates.
+ * In a thread it also does not check whether the member can see a private thread, which Fluxer allows only to its
+ * members and to members who can manage threads, or whether the thread is archived or locked.
+ * The result can become stale immediately after the input was observed
+ *
+ * @example
+ * ```ts
+ * import type { Client, PermissionInput, PermissionTarget } from "@neontechspace/fluxerly"
+ *
+ * export function permissionsExample(client: Client, input: PermissionInput, target: PermissionTarget) {
+ *     return {
+ *         local: client.permissions.calculate(input),
+ *         remote: client.permissions.fetch(target),
+ *     }
+ * }
+ * ```
+ *
+ * @category Roles and permissions
+ */
+export interface PermissionInput {
+    /** Community that owns the member, roles, and optional channel */
+    readonly guild: Guild;
+    /** Membership whose raw permissions are calculated */
+    readonly member: GuildMember;
+    /** Complete role observations needed to resolve everyone and every member role */
+    readonly roles: readonly GuildRole[];
+    /** Target channel's explicit overwrites, or a thread whose permissions come from `parentChannel`. Omit for a
+     * community-level calculation
+     */
+    readonly channel?: GuildChannel;
+    /**
+     * Parent channel of a thread supplied as `channel`, with its permission overwrites. Required when `channel` is a
+     * thread, and rejected otherwise. It must be in the same community and have the ID that the thread's `parentId`
+     * names
+     */
+    readonly parentChannel?: GuildChannel;
+}
+/**
+ * Choose whose permission bits permissions.fetch should calculate from fresh REST reads
+ *
+ * Supply `channelId` to include a separate target-channel read, or omit it for community-level bits.
+ * The client reads guild, member, roles and optional channel in that order under one total deadline, without consulting caches.
+ * When the channel is a thread, the client also reads its parent channel under the same deadline and calculates as
+ * Fluxer does for the thread.
+ * Resources can change between reads. The result is not one simultaneous snapshot and does not guarantee that Fluxer will allow an action
+ *
+ * @category Roles and permissions
+ */
+export interface PermissionTarget extends MemberReference {
+    /** Decimal community-channel ID for a channel-scoped calculation */
+    readonly channelId?: string;
+}
+//# sourceMappingURL=permissions.d.ts.map

package/dist/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,WAAW,eAAe;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;IACrB,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,kFAAkF;IAClF,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAA;IACpC;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAA;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,YAAY,CAAA;CACxC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACrD,oEAAoE;IACpE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC9B"}

package/dist/permissions.js

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

package/dist/permissions.js.map

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

package/dist/pins.d.ts

@@ -0,0 +1,62 @@
+import type { Message, MessageCore } from "./messages.js";
+/** Choose one page of pins for messages.fetchPins.
+ * Pages are ordered by when messages were pinned, not when they were created. Use iteratePins for bounded multi-page traversal.
+ * Fields are captured once. Invalid timestamps, limits and unknown properties are rejected before the request
+ *
+ * @category Messages
+ */
+export interface MessagePinsQuery {
+    /** Maximum pins requested in this page, an integer from 1 through 50, default 50 */
+    readonly limit?: number;
+    /** Pin-time cursor as an ISO 8601 timestamp with seconds and a Z or ±hh:mm offset, such as "2026-01-01T00:00:00Z".
+     * Any fraction length is accepted and the value is sent unchanged. Page ordering and cursor progress retain every fractional digit
+     * and compare timestamps by instant across timezone offsets. Select older pin times. Omit to use Fluxer's
+     * current-time default. Other forms and impossible calendar dates are rejected before dispatch
+     */
+    readonly before?: string;
+}
+/** One pin observed by a request, pairing a message snapshot with the time it was pinned.
+ * Later unpins, repins and message edits do not update this frozen object
+ *
+ * @category Messages
+ */
+export interface MessagePin<M extends MessageCore = Message> {
+    /** Message as returned by this page, using the client's messageFields selection */
+    readonly message: M;
+    /** Time Fluxer pinned the message, preserved as an ISO 8601 string with a timezone */
+    readonly pinnedAt: string;
+}
+/** One frozen page of pins, ordered newest pin time first.
+ * Pins added or removed during traversal, or pins with the same timestamp, can cause a multi-page list to miss messages.
+ * A message can recur on later timestamp pages, even though IDs are unique within one page
+ *
+ * @category Messages
+ */
+export interface MessagePinsPage<M extends MessageCore = Message> {
+    /** Pins in Fluxer's received order, with no more entries than the requested limit */
+    readonly items: readonly MessagePin<M>[];
+    /** True when Fluxer reports more visible pins after this page */
+    readonly hasMore: boolean;
+    /** Timestamp to pass as before, using the last pin time when hasMore is true, otherwise null.
+     * In a manual loop, deduplicate message IDs and stop if this cursor fails to move to an older time
+     */
+    readonly nextBefore: string | null;
+}
+/** Notice that a channel's pins changed, without identifying the pinned or unpinned message.
+ * Fetch pins explicitly for the current list. This event does not fetch it automatically
+ *
+ * @category Events and collectors
+ */
+export interface ChannelPinsUpdate {
+    /** Affected channel ID as a decimal string */
+    readonly channelId: string;
+    /** Community ID when Fluxer supplies it. Omission means no community context was supplied, not a confirmed private channel.
+     * No channel lookup or cache inference supplies this field
+     */
+    readonly guildId?: string;
+    /** Last-pin time supplied by Fluxer as an ISO 8601 string, or null.
+     * This value can stay unchanged after an unpin, so it is not a unique change cursor
+     */
+    readonly lastPinTimestamp: string | null;
+}
+//# sourceMappingURL=pins.d.ts.map

package/dist/pins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pins.d.ts","sourceRoot":"","sources":["../src/pins.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAEzD;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC7B,oFAAoF;IACpF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,WAAW,GAAG,OAAO;IACvD,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAA;IACnB,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,WAAW,GAAG,OAAO;IAC5D,qFAAqF;IACrF,QAAQ,CAAC,KAAK,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,CAAA;IACxC,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;CACrC;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAC9B,8CAA8C;IAC9C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B;;OAEG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB;;OAEG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAA;CAC3C"}

package/dist/pins.js

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

package/dist/pins.js.map

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

package/dist/presence.d.ts

@@ -0,0 +1,84 @@
+import { FluxerlyError } from "./errors.js";
+import { type InputValidationDetail } from "./input-validation.js";
+/** The bot's visible status while connected, with dnd meaning do not disturb.
+ * Use invisible to hide online status, not to disconnect the client.
+ * The status offline is excluded because Fluxer normalizes it to invisible on a connected session
+ *
+ * @category Client and lifecycle
+ */
+export type PresenceStatus = "online" | "idle" | "dnd" | "invisible";
+/**
+ * One custom-status emoji. The variants cannot be combined
+ *
+ * @category Client and lifecycle
+ */
+export type CustomStatusEmoji = {
+    /** Decimal ID of an existing custom emoji. Fluxer checks availability for the bot's account */
+    readonly id: string;
+} | {
+    /** One Unicode emoji. Fluxer validates that it is a supported single emoji */
+    readonly name: string;
+};
+/** Text, emoji and optional expiration for the bot's custom status.
+ * Fluxer makes the final checks for emoji availability, Unicode emoji semantics and whether expiration is still in the future
+ *
+ * @category Client and lifecycle
+ */
+export interface CustomStatusInput {
+    /** Status text, from 1 through 128 UTF-16 code units */
+    readonly text?: string;
+    /** An explicit custom-emoji ID or one Unicode emoji */
+    readonly emoji?: CustomStatusEmoji;
+    /** Future ISO-8601 expiration time. Impossible calendar dates are rejected before retaining the update.
+     * Fluxer rejects an expiry that passes before it receives the update
+     */
+    readonly expiresAt?: string;
+}
+/**
+ * Set the status this bot should publish on its gateway connections.
+ * Use `customStatus: null` to request clearing the custom status.
+ * Omission preserves this client's latest custom-status request, or leaves the provider value unchanged if there is no retained request.
+ * The client copies the latest accepted settings and retains at most one unsent update per local shard, replacing its payload with the latest intent.
+ * Status updates are at least four seconds apart, measured from each actual socket transmission, not queue admission.
+ * It publishes those settings on ready local shards and restores them after READY or RESUMED.
+ * A successful call means the client accepted the settings. It does not mean every shard published them at once or that another user can see them.
+ * Shutdown clears the saved settings and pending local timers
+ *
+ * @category Client and lifecycle
+ */
+export interface PresenceInput {
+    /** Visible status to publish on the bot's live gateway connections */
+    readonly status: PresenceStatus;
+    /** New custom status, null to clear it, or omission to retain the latest custom-status request made by this client */
+    readonly customStatus?: CustomStatusInput | null;
+}
+/** The SDK rejected a status update or member-presence selection before changing its saved settings.
+ * The reason input includes invalid values or a community assigned to a shard this client does not own.
+ * The reason limit means the member selection exceeds a local count or encoded-byte budget
+ *
+ * @category Errors
+ */
+export declare class PresenceError extends FluxerlyError {
+    /** Error tag for identifying PresenceError in a Result */
+    readonly _tag = "PresenceError";
+    /** SDK-owned local input detail, or null for local limits and non-input failures */
+    readonly inputValidation: InputValidationDetail | null;
+    /** Whether local validation failed or the selected members exceeded a local budget */
+    readonly reason: "input" | "limit";
+    /** Describe a rejected presence change. Construction changes no saved presence settings */
+    constructor(options: {
+        /** Whether local validation failed or the selected members exceeded a local budget */
+        readonly reason: PresenceError["reason"];
+        /** Safe local input detail. It never retains rejected values, credentials, or Fluxer data, and names an unsupported key only when it looks like a field name. Defaults to null */
+        readonly inputValidation?: InputValidationDetail | null | undefined;
+        /** Underlying failure retained as the error's cause */
+        readonly cause?: unknown;
+    });
+}
+/**
+ * Expected presence-operation failure. Client closure remains distinct from local input rejection
+ *
+ * @category Errors
+ */
+export type PresenceFailure = PresenceError | import("./errors.js").ClientClosedError;
+//# sourceMappingURL=presence.d.ts.map

package/dist/presence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence.d.ts","sourceRoot":"","sources":["../src/presence.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAoB,MAAM,aAAa,CAAA;AAE7D,OAAO,EAA+B,KAAK,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAE/F;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,WAAW,CAAA;AAEpE;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GACvB;IACI,+FAA+F;IAC/F,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CACtB,GACD;IACI,8EAA8E;IAC9E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACxB,CAAA;AAEP;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAC9B,wDAAwD;IACxD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB,uDAAuD;IACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,iBAAiB,CAAA;IAClC;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;IAC/B,sHAAsH;IACtH,QAAQ,CAAC,YAAY,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAA;CACnD;AAED;;;;;GAKG;AACH,qBAAa,aAAc,SAAQ,aAAa;IAC5C,0DAA0D;IAC1D,QAAQ,CAAC,IAAI,mBAAkB;IAC/B,oFAAoF;IACpF,QAAQ,CAAC,eAAe,EAAE,qBAAqB,GAAG,IAAI,CAAA;IACtD,sFAAsF;IACtF,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAA;IAElC,2FAA2F;IAC3F,YAAY,OAAO,EAAE;QACjB,sFAAsF;QACtF,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,QAAQ,CAAC,CAAA;QACxC,kLAAkL;QAClL,QAAQ,CAAC,eAAe,CAAC,EAAE,qBAAqB,GAAG,IAAI,GAAG,SAAS,CAAA;QACnE,uDAAuD;QACvD,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAC3B,EA+BA;CACJ;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,aAAa,GAAG,OAAO,aAAa,EAAE,iBAAiB,CAAA"}

package/dist/presence.js

@@ -0,0 +1,46 @@
+import { FluxerlyError, operationDetails } from "./errors.js";
+import { operationErrorMessage, operationFailureHint } from "./api-errors.js";
+import { freezeInputValidationDetail } from "./input-validation.js";
+/** The SDK rejected a status update or member-presence selection before changing its saved settings.
+ * The reason input includes invalid values or a community assigned to a shard this client does not own.
+ * The reason limit means the member selection exceeds a local count or encoded-byte budget
+ *
+ * @category Errors
+ */
+export class PresenceError extends FluxerlyError {
+    /** Error tag for identifying PresenceError in a Result */
+    _tag = "PresenceError";
+    /** SDK-owned local input detail, or null for local limits and non-input failures */
+    inputValidation;
+    /** Whether local validation failed or the selected members exceeded a local budget */
+    reason;
+    /** Describe a rejected presence change. Construction changes no saved presence settings */
+    constructor(options) {
+        const { reason, inputValidation = null } = options;
+        super(operationErrorMessage({
+            subject: "Presence",
+            operation: "update",
+            reason,
+            outcome: "notDispatched",
+            inputExplanation: inputValidation?.explanation ??
+                (reason === "limit"
+                    ? "The member selection is too large. The limits are 1,000 members per community, 10,000 members across at most 100 communities, and 4,096 bytes per gateway request"
+                    : null),
+        }), {
+            code: `presence.${reason}`,
+            hint: reason === "limit"
+                ? "Select fewer members, or clear the selection of communities that no longer need member presences"
+                : operationFailureHint({
+                    reason,
+                    outcome: "notDispatched",
+                    inputPath: inputValidation?.path ?? null,
+                }),
+            cause: options.cause,
+            details: operationDetails({ reason }),
+        });
+        this.name = this._tag;
+        this.inputValidation = freezeInputValidationDetail(inputValidation);
+        this.reason = reason;
+    }
+}
+//# sourceMappingURL=presence.js.map

package/dist/presence.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"presence.js","sourceRoot":"","sources":["../src/presence.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC7D,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAC7E,OAAO,EAAE,2BAA2B,EAA8B,MAAM,uBAAuB,CAAA;AA4D/F;;;;;GAKG;AACH,MAAM,OAAO,aAAc,SAAQ,aAAa;IAC5C,0DAA0D;IACjD,IAAI,GAAG,eAAe,CAAA;IAC/B,oFAAoF;IAC3E,eAAe,CAA8B;IACtD,sFAAsF;IAC7E,MAAM,CAAmB;IAElC,2FAA2F;IAC3F,YAAY,OAOX;QACG,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI,EAAE,GAAG,OAAO,CAAA;QAClD,KAAK,CACD,qBAAqB,CAAC;YAClB,OAAO,EAAE,UAAU;YACnB,SAAS,EAAE,QAAQ;YACnB,MAAM;YACN,OAAO,EAAE,eAAe;YACxB,gBAAgB,EACZ,eAAe,EAAE,WAAW;gBAC5B,CAAC,MAAM,KAAK,OAAO;oBACf,CAAC,CAAC,mKAAmK;oBACrK,CAAC,CAAC,IAAI,CAAC;SAClB,CAAC,EACF;YACI,IAAI,EAAE,YAAY,MAAM,EAAE;YAC1B,IAAI,EACA,MAAM,KAAK,OAAO;gBACd,CAAC,CAAC,kGAAkG;gBACpG,CAAC,CAAC,oBAAoB,CAAC;oBACjB,MAAM;oBACN,OAAO,EAAE,eAAe;oBACxB,SAAS,EAAE,eAAe,EAAE,IAAI,IAAI,IAAI;iBAC3C,CAAC;YACZ,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,OAAO,EAAE,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;SACxC,CACJ,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAA;QACrB,IAAI,CAAC,eAAe,GAAG,2BAA2B,CAAC,eAAe,CAAC,CAAA;QACnE,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACxB,CAAC;CACJ"}