@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/input-validation.ts

@@ -0,0 +1,94 @@
+import { unsupportedKeyHint } from "#sdk/internal/suggest"
+
+/** Identifies why the SDK rejected an input before sending a request. The rule may concern its type, allowed range, format or relationship to another field.
+ * These categories do not describe Fluxer errors and are not ready-made messages for users
+ *
+ * @category Errors
+ */
+export type InputValidationConstraint =
+    | "required"
+    | "type"
+    | "format"
+    | "range"
+    | "length"
+    | "allowedValue"
+    | "allowedFields"
+    | "relationship"
+    | "unique"
+    | "size"
+
+/**
+ * Describes why the SDK rejected an input without keeping the rejected value.
+ * Read this detail from an operation error's inputValidation field when it is non-null.
+ * The path names the input field, constraint names the rule, and explanation describes what the SDK accepts.
+ * The SDK reports the first failure it can describe, not every invalid field.
+ * Paths and explanations are SDK-authored, with no rejected values or provider responses.
+ * Every operation input, query and options object rejects keys it does not support before sending, with constraint
+ * allowedFields. The explanation names the key when it is a short identifier, such as a misspelled field name,
+ * suggests the closest supported key and lists the supported keys.
+ * Write application-specific user-facing messages rather than displaying this diagnostic as application copy
+ *
+ * @example
+ * ```ts
+ * import type { InputValidationDetail, MessageOperationFailure } from "@neontechspace/fluxerly"
+ * export function readInputValidation(error: MessageOperationFailure): InputValidationDetail | null {
+ *     return error._tag === "MessageOperationError" ? error.inputValidation : null
+ * }
+ * ```
+ *
+ * @category Errors
+ */
+export interface InputValidationDetail {
+    /** Field or input path the SDK identified as invalid, without copying arbitrary caller keys */
+    readonly path: string
+    /** Kind of rule the input failed, suitable for application-specific error handling */
+    readonly constraint: InputValidationConstraint
+    /** Fixed SDK explanation of the accepted input, not the rejected value or ready-made application text */
+    readonly explanation: string
+}
+
+/** @internal */
+export class InputValidationFailure {
+    constructor(readonly detail: InputValidationDetail) {}
+}
+
+/** @internal */
+export function inputValidationFailure(
+    path: string,
+    constraint: InputValidationConstraint,
+    explanation: string,
+): InputValidationFailure {
+    return new InputValidationFailure(Object.freeze({ path, constraint, explanation }))
+}
+
+/** @internal */
+export function freezeInputValidationDetail(detail: InputValidationDetail | null): InputValidationDetail | null {
+    return detail === null
+        ? null
+        : Object.freeze({ path: detail.path, constraint: detail.constraint, explanation: detail.explanation })
+}
+
+/** @internal Keys up to 64 characters that look like field names, so repeating one never copies arbitrary caller text */
+const nameableKey = /^[A-Za-z_$][\w$]{0,63}$/
+
+/**
+ * @internal Reject the first own key of value that keys does not list, naming it with the closest supported key.
+ * Each validator keeps its supported keys beside it. The path names the containing object, such as input or options,
+ * and subject describes it in lowercase with its article, such as "the history query"
+ */
+export function unsupportedKeyFailure(
+    value: object,
+    keys: readonly string[],
+    path: string,
+    subject: string,
+): InputValidationFailure | undefined {
+    const key = Object.keys(value).find((candidate) => !keys.includes(candidate))
+    if (key === undefined) return undefined
+    const option = path === "options" || path.endsWith(".options")
+    const unsupported = `Unsupported ${option ? "option" : "field"}${nameableKey.test(key) ? ` ${JSON.stringify(key)}` : ""}`
+    return inputValidationFailure(
+        path,
+        "allowedFields",
+        `${unsupported} in ${subject}. ${unsupportedKeyHint(key, keys, option ? "options" : "fields")}`,
+    )
+}

package/src/instance.ts

@@ -0,0 +1,111 @@
+import type { AssetHelpers } from "./assets.js"
+import type { LinkHelpers } from "./helpers.js"
+
+/**
+ * Connect a client to a selected Fluxer server instead of the hosted default.
+ * Omit the whole option to use hosted Fluxer.
+ * When an operation first needs service addresses, the SDK reads `/.well-known/fluxer` from that server without credentials.
+ * It retains the resolved endpoints for this client's lifetime without background refresh
+ *
+ * Select only a trusted instance, since its advertised API and gateway origins can receive this client's credential.
+ * Discovery follows at most three validated unauthenticated redirects.
+ * Requests that send credentials do not follow redirects
+ *
+ * @category Options
+ */
+export interface InstanceOptions {
+    /** Absolute HTTPS root URL that publishes `/.well-known/fluxer`, such as https://fluxer.example.
+     * A path beyond /, query, fragment or embedded credentials is invalid.
+     * HTTP requires allowInsecure, and omitting the whole instance option selects hosted Fluxer
+     */
+    readonly url: string
+    /** Permit HTTP and WS endpoints only for an explicitly selected local or self-hosted instance. Defaults to false */
+    readonly allowInsecure?: boolean
+}
+
+/** Set how long an explicit instance.resolve call may spend finding the server's addresses.
+ * The deadline covers discovery work, but the SDK still waits for owned response cleanup before completing
+ *
+ * @category Options
+ */
+export interface InstanceResolveOptions {
+    /** Time allowed to find service addresses, in milliseconds. Use an integer from 1–2,147,483,647. Default 30,000.
+     * Includes bootstrap redirects and document reads, but required cleanup can take longer
+     */
+    readonly timeoutMs?: number
+}
+
+/** Where the selected Fluxer instance hosts its services, validated from its discovery document.
+ * Services may use different origins, which selecting that instance trusts
+ *
+ * @category Client and lifecycle
+ */
+export interface InstanceEndpoints {
+    /** Public HTTP API base. The SDK appends its documented `/v1` route once, preserving any advertised prefix */
+    readonly apiPublic: string
+    /** Gateway WebSocket base. The SDK adds its required protocol query without deriving another host */
+    readonly gateway: string
+    /** Public media base for instance-specific generated asset URLs */
+    readonly media: string
+    /** Static CDN base for instance-specific generated default-asset URLs */
+    readonly staticCdn: string
+    /** Web application base for instance-specific generated navigation and installation links */
+    readonly webapp: string
+    /** Invite base for instance-specific invite and vanity URLs */
+    readonly invite: string
+}
+
+/**
+ * The selected server's service addresses and matching URL helpers.
+ * This frozen result is retained for one client, not refreshed on each later resolve.
+ * Use assets and links to build URLs for this instance rather than the hosted default.
+ * These helpers make no requests, inspect no credentials and do not refresh discovery or change caches
+ *
+ * @category Client and lifecycle
+ */
+export interface ResolvedInstance {
+    /** Provider code-version indicator from discovery. It is not an API path version */
+    readonly apiCodeVersion: number
+    /** Exact validated service bases from discovery */
+    readonly endpoints: InstanceEndpoints
+    /** Whether this instance advertises temporary upload URLs for attachment transfers */
+    readonly presignedAttachmentUploads: boolean
+    /** Pure asset URL helpers bound to this instance's media and static-CDN bases.
+     * They follow the assets namespace's input-field and fallback rules, return URLs directly and throw AssetUrlError for invalid input
+     */
+    readonly assets: AssetHelpers
+    /** Pure application-link helpers bound to this instance's web application base.
+     * They return URLs directly, throw HelperError for invalid input and perform no navigation or access check
+     */
+    readonly links: LinkHelpers
+    /** The web domain migration that discovery announced, or null when the instance announced none.
+     * Links and OAuth URLs always use the discovered web application base in endpoints, so they follow a migrated domain
+     */
+    readonly domainMigration: InstanceDomainMigration | null
+}
+
+/** A web domain migration announced by instance discovery, such as hosted Fluxer moving its web app to a new domain.
+ * The SDK records an enabled migration at Info when a client first resolves the instance. It changes no endpoint itself
+ *
+ * @category Client and lifecycle
+ */
+export interface InstanceDomainMigration {
+    /** Whether the instance switched the migration on */
+    readonly enabled: boolean
+    /** Share of signed-out web visitors moved to the new domain, in basis points from 0 through 10,000, or null when not supplied */
+    readonly anonymousRolloutBasisPoints: number | null
+    /** Whether standalone app installs are forwarded to the new domain, or null when not supplied */
+    readonly standaloneForwarding: boolean | null
+}
+
+/** Expected instance-resolution failures, including invalid options, connection trouble, deadline expiry, rate limits and client closure.
+ * Default API calls add CancelledError, while native interruption remains in the Effect cause
+ *
+ * @category Errors
+ */
+export type InstanceResolveError =
+    | import("./errors.js").ConnectionError
+    | import("./errors.js").ConnectionTimeoutError
+    | import("./errors.js").RateLimitError
+    | import("./errors.js").ClientClosedError
+    | import("./errors.js").ConfigurationError

package/src/internal/agents-section.ts

@@ -0,0 +1,114 @@
+/**
+ * Writes the SDK's essential rules into an application's AGENTS.md, which many coding agent tools load automatically.
+ * Invariant: Only the text between the Fluxerly markers is replaced, so the rest of the file stays byte for byte
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+const start = "<!-- fluxerly:start -->"
+const end = "<!-- fluxerly:end -->"
+const rulesStart = "<!-- fluxerly-rules:start -->"
+const rulesEnd = "<!-- fluxerly-rules:end -->"
+
+/** Outcome of one run, with the notes to print for the user */
+export interface AgentsSectionResult {
+    readonly status: "created" | "added" | "updated" | "current"
+    readonly file: string
+    readonly notes: readonly string[]
+}
+
+/** Thrown when AGENTS.md or the packaged guide cannot be updated safely, so no file was changed */
+export class AgentsSectionError extends Error {
+    override readonly name = "AgentsSectionError"
+}
+
+// The recorded command must run the installed copy and never download one, since the unscoped fluxerly package on npm is not this SDK
+function refreshCommand(project: string) {
+    if (existsSync(join(project, "pnpm-lock.yaml"))) return "pnpm exec fluxerly agents"
+    if (existsSync(join(project, "bun.lock")) || existsSync(join(project, "bun.lockb")))
+        return "bunx --no-install fluxerly agents"
+    return "npx --no fluxerly agents"
+}
+
+function between(text: string, open: string, close: string, where: string) {
+    const first = text.indexOf(open)
+    const last = text.indexOf(close)
+    if (first < 0 && last < 0) return undefined
+    if (first < 0 || last < first || text.indexOf(open, first + 1) >= 0 || text.indexOf(close, last + 1) >= 0)
+        throw new AgentsSectionError(`${where} must contain exactly one ${open} followed by one ${close}`)
+    return { first, last: last + close.length, inner: text.slice(first + open.length, last) }
+}
+
+/** Build the section for one SDK version from the rules in the packaged agent guide */
+function agentsSection(guide: string, version: string, command: string) {
+    const rules = between(guide, rulesStart, rulesEnd, "The packaged agent guide")
+    if (!rules) throw new AgentsSectionError("The packaged agent guide has no rules section")
+    return [
+        start,
+        "## Fluxerly",
+        "",
+        `These rules come from @neontechspace/fluxerly ${version}. When the version installed in package.json differs, run \`${command}\` to refresh this section`,
+        "",
+        "Read `node_modules/@neontechspace/fluxerly/agents/AGENTS.md` for the complete guide before writing code with the SDK",
+        "",
+        rules.inner.trim(),
+        end,
+    ].join("\n")
+}
+
+/** The section for `project` built from the installed package at `packageRoot` */
+function packagedSection(project: string, packageRoot: string) {
+    const guide = readFileSync(join(packageRoot, "agents/AGENTS.md"), "utf8").replaceAll("\r\n", "\n")
+    const { version } = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8")) as { version: string }
+    return agentsSection(guide, version, refreshCommand(project))
+}
+
+/** The AGENTS.md text that writeAgentsSection creates when `project` has none */
+export function newAgentsFile(project: string, packageRoot: string): string {
+    return `# Agent instructions\n\n${packagedSection(project, packageRoot)}\n`
+}
+
+/**
+ * Add or refresh the Fluxerly section in `project`/AGENTS.md, creating the file when it is missing.
+ * Line endings follow the existing file. Nothing is written when the section is already current or a marker is broken
+ */
+export function writeAgentsSection(project: string, packageRoot: string): AgentsSectionResult {
+    const file = join(project, "AGENTS.md")
+    const notes = [...linkNotes(project)]
+    if (!existsSync(file)) {
+        writeFileSync(file, newAgentsFile(project, packageRoot))
+        return { status: "created", file, notes }
+    }
+    const section = packagedSection(project, packageRoot)
+    const current = readFileSync(file, "utf8")
+    const newline = current.includes("\r\n") ? "\r\n" : "\n"
+    const written = section.replaceAll("\n", newline)
+    const existing = between(current, start, end, "AGENTS.md")
+    if (!existing) {
+        const separator =
+            current.length === 0 || current.endsWith(newline + newline)
+                ? ""
+                : current.endsWith(newline)
+                  ? newline
+                  : newline + newline
+        writeFileSync(file, `${current}${separator}${written}${newline}`)
+        return { status: "added", file, notes }
+    }
+    const next = current.slice(0, existing.first) + written + current.slice(existing.last)
+    if (next === current) return { status: "current", file, notes }
+    writeFileSync(file, next)
+    return { status: "updated", file, notes }
+}
+
+// Some tools read their own instruction file instead of AGENTS.md. Their files are reported, never changed
+function* linkNotes(project: string) {
+    for (const [name, fix] of [
+        ["CLAUDE.md", "add a line containing @AGENTS.md to it"],
+        ["GEMINI.md", "reference AGENTS.md from it"],
+    ] as const) {
+        const path = join(project, name)
+        if (existsSync(path) && !readFileSync(path, "utf8").includes("AGENTS.md"))
+            yield `${name} does not mention AGENTS.md, so tools that read ${name} can miss these rules. To connect them, ${fix}`
+    }
+}

package/src/internal/application.ts

@@ -0,0 +1,51 @@
+/**
+ * Bot application request: Validates the current-application read and projects its response.
+ * Invariant: The operation is a bot-token read, and the projection keeps only the listed public application fields and the owner user ID.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type { BotApplication } from "#sdk/application"
+import { identifier, record } from "./decode/primitives.js"
+
+/** Validated current-application request. Shared REST owns admission, retries, and cleanup */
+export interface BotApplicationRequest<A> {
+    readonly path: string
+    readonly method: "GET"
+    readonly status: 200
+    readonly decode: (value: unknown) => A | undefined
+}
+
+const nullableText = (value: unknown): value is string | null => value === null || typeof value === "string"
+
+function decodeApplication(value: unknown): BotApplication | undefined {
+    if (
+        !record(value) ||
+        !identifier(value.id) ||
+        typeof value.name !== "string" ||
+        !nullableText(value.icon) ||
+        !nullableText(value.description) ||
+        typeof value.bot_public !== "boolean" ||
+        typeof value.bot_require_code_grant !== "boolean" ||
+        !record(value.owner) ||
+        !identifier(value.owner.id)
+    )
+        return undefined
+    return Object.freeze({
+        id: value.id,
+        name: value.name,
+        icon: value.icon,
+        description: value.description,
+        botPublic: value.bot_public,
+        botRequireCodeGrant: value.bot_require_code_grant,
+        ownerId: value.owner.id,
+    })
+}
+
+/** Fetch only the bot-token response's public application fields and owner ID, without cache retention or application management */
+export function applicationCurrent(): BotApplicationRequest<BotApplication> {
+    return {
+        path: "/oauth2/applications/@me",
+        method: "GET",
+        status: 200,
+        decode: decodeApplication,
+    }
+}

package/src/internal/attachment-refresh.ts

@@ -0,0 +1,57 @@
+/**
+ * Attachment URL refresh request: Validates one ordered batch of attachment URLs and decodes the refreshed URLs.
+ * Invariant: Requested strings are never parsed, normalized or dereferenced, and results keep the request order.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type { RefreshedAttachmentUrl } from "#sdk/attachments"
+import { InputValidationFailure, inputValidationFailure } from "#sdk/input-validation"
+import { record } from "./decode/primitives.js"
+
+/** Validated attachment URL refresh request. Shared REST owns admission, deadlines and bounded response parsing */
+export interface AttachmentRefreshRequest {
+    readonly path: "/attachments/refresh-urls"
+    readonly method: "POST"
+    readonly status: 200
+    readonly json: string
+    readonly decode: (value: unknown) => readonly RefreshedAttachmentUrl[] | undefined
+}
+
+/** Build one explicit ordered refresh without parsing, normalizing or dereferencing any requested string */
+export function attachmentRefresh(urls: readonly string[]): AttachmentRefreshRequest | InputValidationFailure {
+    if (!Array.isArray(urls)) return inputValidationFailure("urls", "type", "Attachment URLs must be an array")
+    const length = urls.length
+    if (length < 1 || length > 50)
+        return inputValidationFailure("urls", "length", "Attachment URL refresh requires 1 through 50 entries")
+    const original = Array.from({ length }, (_, index) => urls[index])
+    if (!original.every((url) => typeof url === "string"))
+        return inputValidationFailure("urls[]", "type", "Each attachment URL must be a string")
+    if (!original.every((url) => url.length <= 2_048))
+        return inputValidationFailure(
+            "urls[]",
+            "length",
+            "Each attachment URL must contain at most 2,048 UTF-16 code units",
+        )
+    return {
+        path: "/attachments/refresh-urls",
+        method: "POST",
+        status: 200,
+        json: JSON.stringify({ attachment_urls: original }),
+        decode: (value) => {
+            if (!record(value) || !Array.isArray(value.refreshed_urls)) return undefined
+            if (value.refreshed_urls.length !== original.length) return undefined
+            const refreshed: RefreshedAttachmentUrl[] = []
+            for (let index = 0; index < original.length; index++) {
+                const item = value.refreshed_urls[index]
+                if (
+                    !record(item) ||
+                    typeof item.original !== "string" ||
+                    item.original !== original[index] ||
+                    typeof item.refreshed !== "string"
+                )
+                    return undefined
+                refreshed.push(Object.freeze({ original: item.original, refreshed: item.refreshed }))
+            }
+            return Object.freeze(refreshed)
+        },
+    }
+}