@neontechspace/fluxerly 1000.0.0-nightly.12

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Timothy Enderson
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,129 @@
+# Fluxerly.js
+
+A Fluxer bot SDK for JavaScript, TypeScript and Effect
+
+[Docs](https://preview.fluxerly.neontechspace.com/) ·
+[Quick start](https://preview.fluxerly.neontechspace.com/docs/latest/quick-start/) ·
+[API reference](https://preview.fluxerly.neontechspace.com/docs/latest/api/) ·
+[Changelog](https://preview.fluxerly.neontechspace.com/docs/latest/changelog/) ·
+[Examples](https://preview.fluxerly.neontechspace.com/docs/latest/examples/)
+
+Fluxerly.js handles HTTP requests and gateway connections for messages, events, community resources and commands.
+Both APIs use the same underlying code
+
+| API                       | Import                                   | Application style                                            |
+| ------------------------- | ---------------------------------------- | ------------------------------------------------------------ |
+| JavaScript and TypeScript | `@neontechspace/fluxerly`                | Async/await with a Result that reports success or failure    |
+| Effect                    | `@neontechspace/fluxerly/effect`         | Effect programs with typed failures, scopes and interruption |
+| Testing                   | `@neontechspace/fluxerly/testing`        | Application tests with an in-memory gateway and HTTP server  |
+| Effect testing            | `@neontechspace/fluxerly/effect/testing` | The same test client for Effect programs                     |
+
+The default API does not require learning or setting up Effect.
+Applications that use Effect directly must install a version within the Effect range described below
+
+## What Fluxerly includes
+
+Fluxerly is built for developers at every skill level, from a first bot in one file to large bots that need full control
+
+- **One-file start:** `runBot` connects, stops cleanly on Ctrl+C and explains a failed startup with a suggested fix
+- **Visible errors:** Network calls return a Result instead of throwing, and logs show every failure in full without the token. `FLUXERLY_DEBUG=1` or the `logging` option changes what the logs show
+- **Built-in commands:** Prefix commands with typed arguments, guards, cooldowns, command groups and generated help
+- **Tests without a token:** The `/testing` and `/effect/testing` entry points run a bot against an in-memory gateway and HTTP server
+- **Two APIs, one implementation:** Start with async/await, or choose the native Effect API, with the same features and behavior in both
+- **Ready to grow:** Automatic sharding, session resume across restarts, a process supervisor, rate limiting that never blindly repeats an uncertain write, and metrics and traces through the `observe` option
+- **Agent-ready:** `fluxerly agents` adds the SDK's rules to a project's `AGENTS.md`, and the docs publish `llms.txt`
+
+The result is less infrastructure to build, with testing and application structure already in place
+
+## Requirements
+
+This package is under development and has not reached its first stable release.
+Fluxerly is tested against Node.js 24.15 or newer.
+JavaScript needs no compiler. Use TypeScript 7 to check types or compile TypeScript code, with `@types/node` as a development dependency
+
+Keep the package manager's lockfile for reproducible installs and review the changelog before upgrading.
+Nightly and RC releases can include breaking changes. Install them with `--save-exact`, or `--exact` with Bun, so a fresh install without a lockfile cannot pick up a newer nightly or RC that breaks the API.
+The installed package also contains the changelog as `CHANGELOG.md`
+
+## Start a bot
+
+This bot replies **Pong!** to **!ping**
+
+A bot needs a Fluxer application, its bot token and an invite to a community. [Create a bot](https://preview.fluxerly.neontechspace.com/docs/latest/create-a-bot/) walks through these steps and the permissions the bot needs
+
+To generate a starter project with a test, run `npx @neontechspace/fluxerly init`, `pnpm dlx @neontechspace/fluxerly init` or `bunx @neontechspace/fluxerly init` in the bot's folder, choose JavaScript, TypeScript or Effect, and follow the steps it prints. Adding `--template js`, `--template ts` or `--template effect` skips the question. An existing `.env` is kept, and missing `node_modules` and `.env` lines are added to an existing `.gitignore`. To set up the bot by hand instead:
+
+1. Add `"type": "module"` to the bot project's `package.json`
+2. Install the SDK with `npm install @neontechspace/fluxerly`, `pnpm add @neontechspace/fluxerly` or `bun add @neontechspace/fluxerly`
+3. Save the token in a file named `.env` as `FLUXER_BOT_TOKEN=paste-the-token-here`, and add `.env` to `.gitignore`. Anyone holding the token can act as the bot
+4. Save the following as `bot.js`, or `bot.ts` for TypeScript
+
+The `runBot` function installs the event handler, connects the client and waits for SDK cleanup before finishing. No extra helper files are needed
+
+```js
+import { runBot } from "@neontechspace/fluxerly"
+
+// A failure that stops the bot, such as a rejected token, is logged and sets a failing exit code
+await runBot({
+    token: process.env.FLUXER_BOT_TOKEN,
+    events: {
+        messageCreate: ({ message, reply }) => {
+            if (message.content !== "!ping") return
+            // Returning the reply reports a failed send to the log
+            return reply("Pong!")
+        },
+    },
+})
+```
+
+The same code works in JavaScript and TypeScript.
+Run `node --env-file=.env bot.js`, or `node --env-file=.env bot.ts`, then send **!ping** in a channel where the bot can read and reply
+
+To typecheck TypeScript, add `@types/node` and TypeScript 7 as development dependencies and save this `tsconfig.json` next to the bot. Node.js still runs `bot.ts` directly, and TypeScript only checks it. A generated TypeScript project has this setup and a `check` script that runs the compiler:
+
+```json
+{
+    "compilerOptions": {
+        "target": "ES2024",
+        "module": "NodeNext",
+        "types": ["node"],
+        "strict": true,
+        "noEmit": true,
+        "allowImportingTsExtensions": true,
+        "verbatimModuleSyntax": true,
+        "erasableSyntaxOnly": true
+    }
+}
+```
+
+By default, messages from bots, including the bot's own replies, skip the handler.
+Press Ctrl+C to stop the bot and wait for SDK cleanup.
+A permanent connection failure stops the bot, prints what went wrong with a suggested fix and reports failure to the operating system.
+The bot must still stop or finish work it starts outside the SDK, such as database writes
+
+While it runs, the bot prints startup, readiness, lost connections, long rate-limit waits, shutdown and any handler error in full.
+Set `FLUXERLY_DEBUG=1` to add Debug records, or pass `logging` settings to change levels or send records to another logger.
+Records never contain the token. The SDK is ESM-only, so `require()` fails with an explanation instead of loading it
+
+The same configuration object accepts `commands` for prefix commands and `setup` for other startup work.
+For direct control over connection and shutdown, use `createClient`. Both are available in JavaScript and TypeScript without using Effect
+
+## Start an Effect bot
+
+The Effect API also provides the one-object `runBot` configuration. Its handlers return Effects instead of Promises and Results. The runner uses the application's Effect runtime and services, and waits for cleanup before finishing. The file `examples/starter/bot-effect.ts` shows the complete bot
+
+Before running the Effect example, add Effect 4 to the bot project's dependencies with `npm install effect@4`, `pnpm add effect@4` or `bun add effect@4`.
+The SDK accepts the Effect range listed under `peerDependencies.effect` in `node_modules/@neontechspace/fluxerly/package.json`. The lowest version in that range is the one the SDK is tested against, and later Effect 4 releases are accepted. Effect 3 and Effect 4 prereleases are not
+
+Run `npm ls effect`, `pnpm list effect` or `bun why effect` in the bot project to inspect the installed version.
+Recheck the SDK manifest when upgrading the SDK
+
+## For coding agents
+
+Agent tools do not read instructions inside dependencies on their own. Run `npx --no fluxerly agents`, `pnpm exec fluxerly agents` or `bunx --no-install fluxerly agents` in the bot project, after installing the SDK there, to copy the SDK's rules into its `AGENTS.md`, which many coding agent tools read automatically. Run it again after an SDK update to refresh them.
+The complete guide is `agents/AGENTS.md` inside the installed package. It explains which API to use, how to start and stop the client, and how to check the result
+
+Agents that read web pages can start from the docs' [llms.txt](https://preview.fluxerly.neontechspace.com/llms.txt), which links each documentation version's Markdown guides and condensed API reference
+
+The installed `package.json` lists the supported Node.js version and import paths.
+The files listed in the `types` entries inside `exports` contain the API reference and examples

package/agents/AGENTS.md

@@ -0,0 +1,195 @@
+# Using Fluxerly in an application
+
+Use this guide when writing an application with `@neontechspace/fluxerly`, not when changing the SDK itself.
+Follow the application's instructions and the user's scope first. This guide does not authorize access to accounts, credentials or live channels
+
+Paths starting with `node_modules/@neontechspace/fluxerly/` point into the installed package
+
+## Rules
+
+<!-- fluxerly-rules:start -->
+
+1. Import only from `@neontechspace/fluxerly`, `@neontechspace/fluxerly/effect`, `@neontechspace/fluxerly/testing` or `@neontechspace/fluxerly/effect/testing`, never from its `dist` or `src` files
+2. Use `runBot` for a bot, as in the starter bot. Use `createClient` only when the application needs manual control of connection and shutdown
+3. Network calls return a Result instead of throwing. Check `result.isErr()` before reading `result.value`, or return the call from a handler so the SDK logs a failure
+4. Read the bot token from the environment, such as `FLUXER_BOT_TOKEN`, and keep it out of code, logs and commits
+5. The SDK is ESM-only and needs Node.js 24.15 or newer. Use `import` in a project whose `package.json` sets `"type": "module"`
+6. Use only methods declared in the installed type files, even when a familiar method name seems likely, and report a missing method instead of inventing one
+7. Test a bot with `createTestBot` from `@neontechspace/fluxerly/testing`, which needs no token or network
+
+<!-- fluxerly-rules:end -->
+
+## Start from the starter bot
+
+This is `node_modules/@neontechspace/fluxerly/examples/starter/bot.js`. The same folder has `bot.ts` and the native Effect `bot-effect.ts`
+
+```js
+import { runBot } from "@neontechspace/fluxerly"
+
+// A failure that stops the bot, such as a rejected token, is logged and sets a failing exit code
+await runBot({
+    token: process.env.FLUXER_BOT_TOKEN,
+    events: {
+        messageCreate: ({ message, reply }) => {
+            if (message.content !== "!ping") return
+            // Returning the reply reports a failed send to the log
+            return reply("Pong!")
+        },
+    },
+})
+```
+
+Run it with `node --env-file=.env bot.js`, where `.env` holds `FLUXER_BOT_TOKEN=...`
+
+## Patterns that do not exist in Fluxerly
+
+- No `new Client()` and `client.login(token)`. Use `runBot({ token, ... })`, or `createClient({ token })` and then `client.run()`
+- No intents. Nothing needs to be enabled to receive events
+- No slash commands or interactions. Commands are prefix commands such as `!ping`, through the `commands` option of `runBot`
+- Messages are read-only data without methods, so `message.reply()`, `message.delete()` and `channel.send()` do not exist. Use the `reply` passed to a handler, or `client.messages.send(channelId, content)`
+- A `runBot` event handler receives a context object such as `({ message, reply })`, not the message itself
+- A bot author is detected with `message.author.isBot`. There is no `message.author.bot`, and `runBot` already skips bot-authored messages unless `ignoreBots` is false
+- Fluxer calls servers communities, and the SDK names them guilds, as in `guildId`
+
+## Check a Result
+
+Network and other I/O operations return `ResultAsync`, whose work starts when the method is called. Use `await` to get its `Result`, then check `isErr()` before reading `.value`.
+The `orThrow` helper returns the value and throws the error instead
+
+```ts
+import { createClient } from "@neontechspace/fluxerly"
+
+export async function sendOnce(token: string, channelId: string, content: string) {
+    await using client = createClient({ token })
+    const sent = await client.messages.send(channelId, content)
+    // The caller decides how to report a failed send
+    if (sent.isErr()) throw sent.error
+    return sent.value.id
+}
+```
+
+Sending a single message over HTTP needs no gateway connection. For a long-running bot, reuse one client rather than creating one per message
+
+## Find the right API
+
+1. Read `node_modules/@neontechspace/fluxerly/package.json` for the installed SDK version, required Node.js version and supported import paths under `exports`
+2. Unless the application already uses Effect or explicitly requests it, use `@neontechspace/fluxerly` and its Result-based API without adding an Effect runtime
+3. Follow the `types` path of the chosen entry, such as `dist/index.d.ts`, and search that file for the requested member.
+   Read its JSDoc and follow referenced declarations for the needed options and error types, rather than reading the entire file.
+   These comments document the installed SDK version
+4. Look for existing SDK helpers, command routing and paginated iterators before writing equivalent code
+
+When the declarations do not answer a question, the documentation website has files for AI tools.
+The index at https://preview.fluxerly.neontechspace.com/docs/latest/llms.txt links every guide as a small Markdown file, `llms-full.txt` holds every guide and `llms-reference.txt` holds a condensed API reference.
+Prefer the installed declarations when they differ from the website
+
+## Project requirements
+
+- A `require()` call fails with an error that explains the SDK is ESM-only
+- TypeScript checks need TypeScript 7 and `@types/node`, for example with `"types": ["node"]`, because handler signals are `AbortSignal` values and clients support `await using`. Running `node bot.ts` directly needs no compiler
+- A missing or blank token is logged with a hint, sets exit code 1 and returns `ConfigurationError` from `runBot` instead of throwing
+
+Keep the application's existing module and TypeScript settings when they work with the SDK. Report any incompatibility before proposing changes
+
+## Build the bot
+
+- `runBot` takes one options object with the client settings, `events` handlers, prefix `commands`, a `setup(client, { signal })` callback for other startup work and `onError`. By default it skips messages written by bots, and the default API's `runBot` also stops cleanly on SIGINT and SIGTERM. Set `ignoreBots: false` or `processSignals: false` to turn either off. The native Effect `runBot` from `@neontechspace/fluxerly/effect` handles those signals only with `processSignals: true`, because an Effect launcher such as `NodeRuntime.runMain` may already handle them.
+  It checks every option before creating a client, then connects and resolves only after the bot stopped and SDK cleanup finished. A failure that stops the bot is logged once and sets `process.exitCode` to 1, so `await runBot({...})` needs no try/catch. Pass `reportFailure: false` only when the application handles the returned failure itself
+- For prefix commands, pass `commands: { prefix, commands: { name: { arguments, guard, cooldown, hidden, execute } } }` to `runBot`.
+  Guards come from `guards`: `guildOnly()`, `dmOnly()`, `ownerOnly()` for the application's owner, `ownerOnly(ids)` and `requirePermissions(names)`. A cooldown is `{ durationMs, per: "user" | "channel" | "guild" }`.
+  A `hidden: true` command is left out of help and suggestions but still runs, so guard commands that need protection
+- With `createClient`, register handlers with `client.on` or `client.subscribe` before `connect` or `run`.
+  The `run` method waits until the client stops, not just until it connects. The `shutdown` method closes the client permanently
+
+Local work returns plain values and needs no Result handling: Creating clients and command routers, registering handlers, cache `get` lookups and helpers such as `format` and `colors`.
+Misuse of local work, such as invalid options or a missing token, throws `ConfigurationError` or the helper's own error at once
+
+Methods returning `AsyncIterable`, such as `messages.iterateHistory`, start work when iteration begins. Use `for await` and check each returned `Result`
+
+## Errors and cleanup
+
+Expected runtime failures return `Err`. Unexpected SDK failures can throw or reject a Promise, so release clients with `await using` or in `finally`.
+Every SDK error extends `FluxerlyError` with a stable `code`, an optional `hint` and a `cause`. Use `describeError(error)` to print one, `errors.apiCode(error)` to branch on a Fluxer rejection such as `"missingPermissions"`, and `errors.isRetryable(error)` before repeating a call
+
+Failures without a returned result, such as a handler that throws or returns an `Err`, go to the client's `onError` option or are logged at Error with the full error.
+Do not wrap every handler in a catch that only logs. Let the SDK report it, or pass `onError` to route reports to the application's own error tracking
+
+Keep shutdown in one place in the application. That code must also close the subscriptions, collectors and iterators it creates, with `close()` or `await using`.
+A subscription registered after shutdown began is returned already closed with a Warn record, and a collector registered then reports `ClientClosedError` from its `result()`
+
+## Tests
+
+Test a `runBot` bot by passing its own options object to `createTestBot` from `@neontechspace/fluxerly/testing`. It runs the bot's events, commands and `setup` against an in-memory Fluxer, with no token or network. Use `createTestClient` for code written against a client.
+Both return a real client with the controls `ready()`, `emit(type, payload)` for Fluxer events such as `MESSAGE_CREATE`, `rest.respond(matcher, response)`, `requests()`, `commands()`, `logs()`, `counters()` and `disconnect()`. The shared `fixtures` build event payloads.
+Send a user message with `say(content)` on a test bot, which resolves with the messages the bot sent. Message sends and edits without a `rest.respond` fixture receive an echoed message.
+Wait for a request with `next()` on the route that `rest.respond` returns, and for a quiet bot with `idle()`, instead of sleeping. Waits have no deadline unless `timeoutMs` is passed, so the test runner's timeout bounds a hung test.
+A handler or command failure without `onError` makes shutdown fail with `UnhandledTestFailuresError`, unless the test reads it from `failures()`.
+Release the default test client with `await using` or `shutdown()`
+
+## Before sending requests
+
+- Keep IDs as decimal strings, not JavaScript numbers, and check documented units on timeout options
+- Check whether the chosen method reads cached data or fetches it from Fluxer. An object missing from the cache may still exist on Fluxer
+- Keep tokens out of logs, examples, fixtures and error reports
+- Check the documented cancellation and retry behavior before adding retries.
+  Cancellation does not undo a write that was already sent.
+  When a write's outcome is unknown, check Fluxer's current state if authorized rather than sending the same write again
+
+## Finish with evidence
+
+Check the types of the application's actual imports and changed code against the installed package.
+Test success, expected failure and cleanup through the public API, preferably with the testing entry points
+
+Run live checks only against explicitly authorized targets and clean up test-owned resources
+
+A successful send response does not prove that the recipient received the message or that the full task succeeded.
+Check the result requested by the user. Report anything that could not be tested or accessed instead of claiming it is complete
+
+## Only for native Effect applications
+
+Use an Effect version within the `peerDependencies.effect` range in the installed SDK's `package.json`.
+The lowest version in that range is the one the SDK is tested against. Later Effect 4 releases are accepted, but Effect 3 and Effect 4 prereleases are not
+
+Effect operations describe work but do not start it until executed.
+Compose them with `yield*` inside `Effect.gen`, keep the scope open while its resources are needed, and execute the program from the application's entry point.
+Do not return a usable client or collector from a scope that has already closed
+
+```ts
+import { Effect } from "effect"
+import { createClient } from "@neontechspace/fluxerly/effect"
+
+export function sendOnce(token: string, channelId: string, content: string) {
+    const program = Effect.scoped(
+        Effect.gen(function* () {
+            const client = yield* createClient({ token })
+            const sent = yield* client.messages.send(channelId, content)
+            return sent.id
+        }),
+    )
+    return Effect.runPromise(program)
+}
+```
+
+The native `runBot` takes the same options object with handlers that return Effects. Match `examples/starter/bot-effect.ts`.
+For Layer-based programs, provide `FluxerClient.layer(options)` or `FluxerClient.layerConfig({ token: Config.Redacted("FLUXER_BOT_TOKEN") })` and read the client with `yield* FluxerClient`. Building the layer does not connect.
+Native logging goes through the program's Effect logger. The native test helpers from `@neontechspace/fluxerly/effect/testing` are scoped
+
+Re-running an Effect can repeat a remote write.
+Handle typed failures separately from unexpected defects and interruption.
+Check each member's declaration rather than assuming every native member is an Effect
+
+## Advanced
+
+- Build a command router with `commands.create` and `attach` it to a client. Router options add `use` middleware, `onReject: "reply"` feedback, `mentionPrefix` and `cooldowns: { maxEntries }`, and `router.help` or the command context's `help()` builds help pages. The context's `sendHelp()` sends them, and its `paginate(pages)` shows pages that the command's author flips with reactions
+- Use `client.use(middleware)` for event middleware around every later `on` handler
+- For Fluxer API routes without an SDK method, use `client.rest.request({ method, path })`, which shares the client's queue, rate limits and logging. For gateway commands without an SDK method, use `client.gateway.send(shardId, op, d)`. Check the installed declarations for an SDK method first
+- The client logs startup, readiness, lost connections, long rate-limit waits, event drops, shutdown and every application failure by default. Records never contain the token or other credentials.
+  Adjust output with the `logging` option rather than filtering console output, and change levels while running with `client.logging.configure`: `level`, per-category `categories`, `debug`, `format` (`"pretty"` or `"json"`), `sink` to forward records to another logger, and `dedupe`.
+  Set `FLUXERLY_DEBUG=1`, or a list of categories, for Debug records. Leave `unsafe` payload logging off unless explicitly authorized for local debugging.
+  Each record has a stable `code`, such as `rest.rejected`. The documentation website lists every error and log code
+- Read `client.diagnostics().counters` for failure, drop, retry and reconnect totals
+
+## Keep this guide in the project
+
+Run `npx --no fluxerly agents`, `pnpm exec fluxerly agents` or `bunx --no-install fluxerly agents` in the application's folder to copy the rules above into its AGENTS.md, which many coding agent tools read automatically.
+Running it again after an SDK update refreshes only that section

package/dist/api/default/application.d.ts

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

package/dist/api/default/application.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"application.d.ts","sourceRoot":"","sources":["../../../src/api/default/application.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,cAAc,EACd,8BAA8B,EAC9B,qCAAqC,EACxC,MAAM,kBAAkB,CAAA;AACzB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAErE;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,WAAW,qBAAqB;IAClC;;;OAGG;IACH,KAAK,CACD,OAAO,CAAC,EAAE,qCAAqC,GAChD,WAAW,CAAC,cAAc,EAAE,8BAA8B,GAAG,cAAc,GAAG,kBAAkB,CAAC,CAAA;CACvG"}

package/dist/api/default/application.js

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

package/dist/api/default/application.js.map

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