@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/internal/transfer-source.ts

@@ -0,0 +1,359 @@
+/**
+ * Attachment transfer sources: Exact-length readers over copied bytes, sized files and finite streams.
+ * Invariant: Each source verifies its exact byte count and awaits acquired reader cleanup without buffering unknown-length
+ * streams, and only copied byte sources can replay after an inline rate-limit rejection. Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import { setImmediate as yieldToHost } from "node:timers/promises"
+import type { AttachmentStreamReadResult, AttachmentStreamReader, AttachmentStreamSource } from "#sdk/attachments"
+import type { FilePart } from "./attachments.js"
+
+const chunkBytes = 65_536
+
+export type AttachmentTransferBody = {
+    readonly body: ReadableStream<Uint8Array>
+    verify(): Promise<void>
+    finish(): Promise<void>
+    stop(): Promise<void>
+}
+
+/** Marks reader finalization failures so the REST boundary does not present them as transport failures */
+export class AttachmentTransferCleanupError extends Error {
+    constructor(cause: unknown) {
+        super("Closing the attachment file or stream reader failed", { cause })
+        this.name = "AttachmentTransferCleanupError"
+    }
+}
+
+/** Keeps an exact-length failure separate from a source cleanup defect */
+export class AttachmentTransferVerificationCleanupError extends Error {
+    constructor(
+        readonly verification: unknown,
+        readonly cleanup: unknown,
+    ) {
+        super("The attachment did not supply its declared size, and closing its reader also failed", { cause: cleanup })
+        this.name = "AttachmentTransferVerificationCleanupError"
+    }
+}
+
+function validChunk(value: unknown): value is Uint8Array {
+    return value instanceof Uint8Array && value.buffer instanceof ArrayBuffer
+}
+
+function readResult(value: unknown): AttachmentStreamReadResult | undefined {
+    if (typeof value !== "object" || value === null) return undefined
+    const done = "done" in value ? value.done : undefined
+    if (done === true)
+        return { done: true, value: "value" in value && validChunk(value.value) ? value.value : undefined }
+    if (done !== false && done !== undefined) return undefined
+    if (!("value" in value) || !validChunk(value.value)) return undefined
+    return { done: false, value: value.value }
+}
+
+async function readNonempty(reader: AttachmentStreamReader, closed: () => boolean, invalid: string) {
+    let emptyReads = 0
+    for (;;) {
+        if (closed()) throw new Error("Attachment source closed")
+        const next = readResult(await reader.read())
+        if (closed()) throw new Error("Attachment source closed")
+        if (!next) throw new Error(invalid)
+        if (next.done) return undefined
+        if (next.value.byteLength !== 0) return next.value
+        // Empty chunks are valid, but immediately resolved reads must not starve
+        // host timers and cancellation, including during the final EOF check
+        if (++emptyReads === 256) {
+            emptyReads = 0
+            await yieldToHost()
+        }
+    }
+}
+
+async function completeCleanup(actions: readonly (() => void | PromiseLike<void>)[]) {
+    const failures: unknown[] = []
+    for (const action of actions) {
+        try {
+            await action()
+        } catch (error) {
+            failures.push(error)
+        }
+    }
+    if (failures.length === 1) throw failures[0]
+    if (failures.length > 1) throw new AggregateError(failures, "Attachment source cleanup failed")
+}
+
+/** One operation-owned exact-length source. Byte inputs are copied before construction, while file and stream sources remain caller-owned outside an acquired reader */
+export class AttachmentTransferSource {
+    readonly size: number
+    /** Byte inputs are snapshot-owned and can recreate a fully consumed inline body after a confirmed rate-limit rejection */
+    readonly replayable: boolean
+    #streamReader: AttachmentStreamReader | undefined
+    #streamPending: Uint8Array | undefined
+    #streamOffset = 0
+    #streamPosition = 0
+    #closed = false
+
+    constructor(private readonly file: FilePart) {
+        this.size = file.size
+        this.replayable = file.source.kind === "bytes"
+    }
+
+    async #closeStream(cancel: boolean) {
+        this.#closed = !this.replayable
+        const reader = this.#streamReader
+        this.#streamReader = undefined
+        this.#streamPending = undefined
+        this.#streamOffset = 0
+        if (!reader) return
+        await completeCleanup([...(cancel ? [() => reader.cancel()] : []), () => reader.releaseLock()])
+    }
+
+    async close() {
+        // Copied bytes have no caller-owned reader or mutable source to release. They can
+        // recreate an inline multipart body after a confirmed 429, including when the server
+        // replied before reading the first body
+        if (!this.replayable) this.#closed = true
+        await this.#closeStream(true)
+    }
+
+    #streamReaderForRead(): AttachmentStreamReader {
+        if (this.#closed) throw new Error("Attachment source closed")
+        if (this.#streamReader) return this.#streamReader
+        if (this.file.source.kind !== "stream") throw new Error("Attachment source is not a stream")
+        const reader = this.file.source.stream.getReader()
+        if (!isAttachmentStreamReader(reader))
+            throw new Error("The attachment stream getReader() result must have read, cancel, and releaseLock methods")
+        this.#streamReader = reader
+        return reader
+    }
+
+    async #nextStreamChunk(): Promise<Uint8Array | undefined> {
+        if (!this.#streamPending || this.#streamOffset === this.#streamPending.byteLength) {
+            this.#streamPending = undefined
+            this.#streamOffset = 0
+            this.#streamPending = await readNonempty(
+                this.#streamReaderForRead(),
+                () => this.#closed,
+                "The attachment stream reader returned a result that is not { done, value } with Uint8Array bytes",
+            )
+        }
+        return this.#streamPending
+    }
+
+    #streamRange(offset: number, size: number): AttachmentTransferBody {
+        const owner = this
+        if (offset !== this.#streamPosition) throw new Error("Attachment stream parts must remain sequential")
+        let remaining = size
+        let ended = false
+        let finished = false
+        let controller: ReadableStreamDefaultController<Uint8Array> | undefined
+        const stream = new ReadableStream<Uint8Array>(
+            {
+                pull: async (value) => {
+                    if (remaining === 0) {
+                        ended = true
+                        value.close()
+                        return
+                    }
+                    const chunk = await owner.#nextStreamChunk()
+                    if (!chunk) throw new Error("Attachment stream ended before its declared size")
+                    const available = chunk.byteLength - owner.#streamOffset
+                    const length = Math.min(available, remaining, chunkBytes)
+                    const next = chunk.subarray(owner.#streamOffset, owner.#streamOffset + length)
+                    owner.#streamOffset += length
+                    owner.#streamPosition += length
+                    remaining -= length
+                    value.enqueue(next)
+                },
+                cancel: async () => {
+                    ended = true
+                    await owner.close()
+                },
+                start(value) {
+                    controller = value
+                },
+            },
+            { highWaterMark: 0 },
+        )
+        return {
+            body: stream,
+            async verify() {
+                if (!ended || remaining !== 0) throw new Error("Attachment stream did not finish its requested range")
+                if (owner.#streamPosition !== owner.size) return
+                const extra = await owner.#nextStreamChunk()
+                if (extra) throw new Error("Attachment stream exceeded its declared size")
+            },
+            async finish() {
+                finished = true
+                if (owner.#streamPosition !== owner.size) return
+                try {
+                    await owner.#closeStream(false)
+                } catch (error) {
+                    throw new AttachmentTransferCleanupError(error)
+                }
+            },
+            async stop() {
+                if (!ended) {
+                    ended = true
+                    controller?.error(new Error("Attachment upload body closed"))
+                }
+                if (!finished) await owner.close()
+            },
+        }
+    }
+
+    #rangeStream(stream: AttachmentStreamSource, size: number): AttachmentTransferBody {
+        let reader: AttachmentStreamReader | undefined
+        let closed = false
+        let pending: Uint8Array | undefined
+        let pendingOffset = 0
+        let remaining = size
+        let ended = false
+        let controller: ReadableStreamDefaultController<Uint8Array> | undefined
+        const take = async (): Promise<Uint8Array | undefined> => {
+            if (closed) throw new Error("Attachment source closed")
+            if (!reader) {
+                const candidate = stream.getReader()
+                if (!isAttachmentStreamReader(candidate))
+                    throw new Error(
+                        "The attachment file stream getReader() result must have read, cancel, and releaseLock methods",
+                    )
+                reader = candidate
+            }
+            if (!pending || pendingOffset === pending.byteLength) {
+                pending = undefined
+                pendingOffset = 0
+                pending = await readNonempty(
+                    reader,
+                    () => closed,
+                    "The attachment file stream reader returned a result that is not { done, value } with Uint8Array bytes",
+                )
+            }
+            return pending
+        }
+        const body = new ReadableStream<Uint8Array>(
+            {
+                pull: async (value) => {
+                    if (remaining === 0) {
+                        ended = true
+                        value.close()
+                        return
+                    }
+                    const next = await take()
+                    if (!next) throw new Error("Attachment file ended before its reported size")
+                    const length = Math.min(next.byteLength - pendingOffset, remaining, chunkBytes)
+                    pendingOffset += length
+                    remaining -= length
+                    value.enqueue(next.subarray(pendingOffset - length, pendingOffset))
+                },
+                cancel: async () => {
+                    ended = true
+                    await release(true)
+                },
+                start(value) {
+                    controller = value
+                },
+            },
+            { highWaterMark: 0 },
+        )
+        const release = async (cancel: boolean) => {
+            closed = true
+            if (!reader) return
+            const current = reader
+            reader = undefined
+            await completeCleanup([...(cancel ? [() => current.cancel()] : []), () => current.releaseLock()])
+        }
+        return {
+            body,
+            async verify() {
+                if (!ended || remaining !== 0) throw new Error("Attachment file did not finish its requested range")
+                if (pending && pendingOffset < pending.byteLength)
+                    throw new Error("Attachment file exceeded its reported size")
+                pending = undefined
+                pendingOffset = 0
+                const extra = await take()
+                if (extra) throw new Error("Attachment file exceeded its reported size")
+            },
+            async finish() {
+                try {
+                    await release(false)
+                } catch (error) {
+                    throw new AttachmentTransferCleanupError(error)
+                }
+            },
+            async stop() {
+                if (!ended) {
+                    ended = true
+                    controller?.error(new Error("Attachment upload body closed"))
+                }
+                await release(true)
+            },
+        }
+    }
+
+    #bytesRange(data: Uint8Array, offset: number, size: number): AttachmentTransferBody {
+        let position = offset
+        const end = offset + size
+        let ended = false
+        let controller: ReadableStreamDefaultController<Uint8Array> | undefined
+        const body = new ReadableStream<Uint8Array>(
+            {
+                pull(value) {
+                    if (position === end) {
+                        ended = true
+                        value.close()
+                        return
+                    }
+                    const next = Math.min(position + chunkBytes, end)
+                    value.enqueue(data.subarray(position, next))
+                    position = next
+                },
+                cancel() {
+                    ended = true
+                },
+                start(value) {
+                    controller = value
+                },
+            },
+            { highWaterMark: 0 },
+        )
+        return {
+            body,
+            async verify() {
+                if (!ended || position !== end) throw new Error("Attachment bytes did not finish their requested range")
+            },
+            async finish() {},
+            async stop() {
+                if (!ended) {
+                    ended = true
+                    controller?.error(new Error("Attachment upload body closed"))
+                }
+            },
+        }
+    }
+
+    open(offset: number, size: number): AttachmentTransferBody {
+        if (this.#closed || offset < 0 || size < 0 || offset + size > this.size)
+            throw new Error("Invalid attachment range")
+        if (this.file.source.kind === "bytes") {
+            return this.#bytesRange(this.file.source.data, offset, size)
+        }
+        if (this.file.source.kind === "file") {
+            const slice = this.file.source.file.slice(offset, offset + size)
+            if (!slice || typeof slice.stream !== "function")
+                throw new Error("The attachment file slice() result must have a stream method")
+            return this.#rangeStream(slice.stream(), size)
+        }
+        return this.#streamRange(offset, size)
+    }
+}
+
+function isAttachmentStreamReader(value: unknown): value is AttachmentStreamReader {
+    if (typeof value !== "object" || value === null) return false
+    return (
+        "read" in value &&
+        typeof value.read === "function" &&
+        "cancel" in value &&
+        typeof value.cancel === "function" &&
+        "releaseLock" in value &&
+        typeof value.releaseLock === "function"
+    )
+}

package/src/internal/transport/http.ts

@@ -0,0 +1,46 @@
+/**
+ * HTTP transport seam: The one fetch-shaped function that REST, instance discovery, OAuth and attachment transfers call.
+ * Invariant: The platform implementation looks up the global fetch on every request, so no module captures a transport
+ * at import time. Callers always pass their own redirect policy and abort signal, and every transport an SDK owner uses
+ * adds exactly one User-Agent header, replacing any caller-built value.
+ * Implements [SDK contracts: Connection and recovery](/docs/SDK-CONTRACTS.md#connection-and-recovery)
+ */
+import { defaultUserAgent } from "./user-agent.js"
+
+/** Fetch-shaped HTTP transport. It must honor init.signal and init.redirect like the platform fetch */
+export type HttpTransport = (url: string, init: RequestInit) => Promise<Response>
+
+/** Platform fetch, resolved at call time */
+export const platformHttpTransport: HttpTransport = (url, init) => globalThis.fetch(url, init)
+
+/** Copy request headers into a plain record without any User-Agent, keeping the SDK's header-name spelling */
+function headerRecord(headers: RequestInit["headers"]): Record<string, string> {
+    const result: Record<string, string> = {}
+    if (headers === undefined) return result
+    if (headers instanceof Headers || Array.isArray(headers)) {
+        new Headers(headers).forEach((value, name) => {
+            result[name] = value
+        })
+    } else Object.assign(result, headers)
+    for (const name of Object.keys(result)) if (name.toLowerCase() === "user-agent") delete result[name]
+    return result
+}
+
+/**
+ * Send every request through a transport with the given User-Agent. A synchronous throw from the wrapped transport
+ * becomes a rejected promise, so callers see one failure path for replaced implementations
+ */
+export function withUserAgent(http: HttpTransport, userAgent: () => string): HttpTransport {
+    return (url, init) => {
+        try {
+            return Promise.resolve(
+                http(url, { ...init, headers: { ...headerRecord(init.headers), "User-Agent": userAgent() } }),
+            )
+        } catch (error) {
+            return Promise.reject(error)
+        }
+    }
+}
+
+/** Platform fetch with the SDK's default User-Agent, used by every owner created without a caller transport */
+export const defaultHttpTransport: HttpTransport = withUserAgent(platformHttpTransport, defaultUserAgent)

package/src/internal/transport/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Transport seam entry: The HTTP and WebSocket implementations one SDK owner uses for all network I/O.
+ * Invariant: REST, instance discovery, OAuth and the gateway reach the network only through a Transport, every owner
+ * created without an explicit one uses the platform fetch and the selected ws library, and every Transport sends one
+ * User-Agent with each HTTP request and gateway handshake.
+ * Implements [SDK contracts: Connection and recovery](/docs/SDK-CONTRACTS.md#connection-and-recovery)
+ */
+import { defaultHttpTransport, type HttpTransport } from "./http.js"
+import { defaultSocketFactory, type SocketFactory } from "./socket.js"
+
+export { defaultHttpTransport, platformHttpTransport, withUserAgent, type HttpTransport } from "./http.js"
+export type { GatewaySocket, SocketData, SocketFactory } from "./socket.js"
+export { defaultSocketFactory, platformSocketFactory, SocketState, withSocketUserAgent } from "./socket.js"
+export { defaultUserAgent, userAgentMaxLength, validUserAgent } from "./user-agent.js"
+
+/** Network implementations shared by one client, OAuth client or webhook client */
+export interface Transport {
+    readonly http: HttpTransport
+    readonly sockets: SocketFactory
+}
+
+/** Platform fetch and the selected ws transport, both with the SDK's default User-Agent */
+export const defaultTransport: Transport = Object.freeze({ http: defaultHttpTransport, sockets: defaultSocketFactory })

package/src/internal/transport/socket.ts

@@ -0,0 +1,71 @@
+/**
+ * WebSocket transport seam: The ws-shaped socket factory the gateway session opens its connection through.
+ * Invariant: Only this module imports ws, so gateway code depends on the GatewaySocket shape rather than the library,
+ * and the default factory applies the SDK's receive limit, redirect policy and User-Agent handshake header exactly as
+ * supplied.
+ * Implements [SDK contracts: Connection and recovery](/docs/SDK-CONTRACTS.md#connection-and-recovery)
+ */
+import WebSocket from "ws"
+import { defaultUserAgent } from "./user-agent.js"
+
+/** WebSocket ready states, matching the ws and WHATWG numbering */
+export const SocketState = Object.freeze({ connecting: 0, open: 1, closing: 2, closed: 3 } as const)
+
+/** Received message data: The forms ws delivers (a Buffer is a Uint8Array), or a string from another WebSocket implementation */
+export type SocketData = Uint8Array | ArrayBuffer | readonly Uint8Array[] | string
+
+/** Options the gateway passes to every socket it opens */
+export interface SocketOptions {
+    /** Compression is never negotiated, so received sizes are wire sizes */
+    readonly perMessageDeflate: false
+    /** The gateway URL is trusted as given. Redirects are rejected */
+    readonly followRedirects: false
+    /** Largest accepted message in bytes, enforced before decoding text or parsing JSON, including fragments */
+    readonly maxPayload: number
+    /** Handshake headers. The owner's socket factory adds the User-Agent here */
+    readonly headers?: Readonly<Record<string, string>>
+}
+
+/** Socket options after the owner's factory has added its handshake headers */
+export interface HeaderedSocketOptions extends SocketOptions {
+    readonly headers: Readonly<Record<string, string>>
+}
+
+/** The subset of a ws WebSocket that the gateway session uses */
+export interface GatewaySocket {
+    readonly readyState: number
+    send(data: string, callback: (error?: Error) => void): void
+    close(code: number): void
+    terminate(): void
+    on(event: "message", listener: (data: SocketData, binary: boolean) => void): unknown
+    on(event: "error", listener: (error: Error & { code?: string }) => void): unknown
+    on(event: "close", listener: (code: number) => void): unknown
+    once(event: "close", listener: () => void): unknown
+    off(event: "message", listener: (data: SocketData, binary: boolean) => void): unknown
+    off(event: "error", listener: (error: Error & { code?: string }) => void): unknown
+    off(event: "close", listener: (() => void) | ((code: number) => void)): unknown
+}
+
+/** Open one socket. Connection failures arrive as error or close events, and a synchronous throw is treated as an SDK defect */
+export type SocketFactory = (url: string, options: SocketOptions) => GatewaySocket
+
+/** The ws library, sending exactly the given options */
+export const platformSocketFactory = (url: string, options: HeaderedSocketOptions): GatewaySocket =>
+    new WebSocket(url, options)
+
+/** Open every socket with the given User-Agent handshake header, replacing any other User-Agent value */
+export function withSocketUserAgent(
+    sockets: (url: string, options: HeaderedSocketOptions) => GatewaySocket,
+    userAgent: () => string,
+): SocketFactory {
+    return (url, options) => {
+        const headers: Record<string, string> = {}
+        for (const [name, value] of Object.entries(options.headers ?? {}))
+            if (name.toLowerCase() !== "user-agent") headers[name] = value
+        headers["User-Agent"] = userAgent()
+        return sockets(url, { ...options, headers: Object.freeze(headers) })
+    }
+}
+
+/** The ws library with the SDK's default User-Agent */
+export const defaultSocketFactory: SocketFactory = withSocketUserAgent(platformSocketFactory, defaultUserAgent)

package/src/internal/transport/user-agent.ts

@@ -0,0 +1,46 @@
+/**
+ * The SDK's default User-Agent: Product token, installed version and homepage from the package manifest.
+ * Invariant: The manifest is read at most once, on the first request rather than at import, and a missing or malformed
+ * manifest only removes the version or homepage comment from the value.
+ * Implements [SDK contracts: Connection and recovery](/docs/SDK-CONTRACTS.md#connection-and-recovery)
+ */
+import { readFileSync } from "node:fs"
+import { record } from "../decode/primitives.js"
+import { sdkVersion } from "../logging.js"
+
+/** Longest caller-supplied User-Agent */
+export const userAgentMaxLength = 512
+
+let cached: string | undefined
+
+/** The package homepage, or undefined when the manifest cannot supply an HTTPS URL */
+function homepage(): string | undefined {
+    try {
+        const manifest = JSON.parse(readFileSync(new URL("../../../package.json", import.meta.url), "utf8")) as unknown
+        const value = record(manifest) ? manifest.homepage : undefined
+        return typeof value === "string" && /^https:\/\/[\x21-\x7e]+$/.test(value) ? value : undefined
+    } catch {
+        // allow-silent: A missing manifest only removes the homepage comment from the User-Agent
+        return undefined
+    }
+}
+
+/** `Fluxerly.js/<version> (+<homepage>)`, read once from the SDK manifest */
+export function defaultUserAgent(): string {
+    if (cached !== undefined) return cached
+    const version = sdkVersion()
+    const home = homepage()
+    cached = `Fluxerly.js/${/^[\x21-\x7e]+$/.test(version) ? version : "unknown"}${home === undefined ? "" : ` (+${home})`}`
+    return cached
+}
+
+/** Whether a caller value is a usable User-Agent: Printable ASCII, bounded, without surrounding spaces */
+export function validUserAgent(value: unknown): value is string {
+    return (
+        typeof value === "string" &&
+        value.length >= 1 &&
+        value.length <= userAgentMaxLength &&
+        /^[\x20-\x7e]+$/.test(value) &&
+        value.trim() === value
+    )
+}

package/src/internal/uploads.ts

@@ -0,0 +1,111 @@
+/**
+ * Presigned attachment upload plans.
+ * Invariant: A plan authorizes individual destinations without sending bot credentials to them. Inline fallback is limited to a
+ * disabled presigned-upload feature or its explicit planning rejection, not a failed PUT or an uncertain message request.
+ * Failed operations may leave provider-owned temporary uploads, and cancellation cannot roll back a dispatched message.
+ * Implements [SDK contracts: Delivery, requests and caches](/docs/SDK-CONTRACTS.md#delivery-requests-and-caches)
+ */
+import type { FilePart } from "./attachments.js"
+import { record } from "./decode/primitives.js"
+
+export type UploadPlan = {
+    id: number
+    filename: string
+    contentType: string
+    key: string
+    uploadId?: string
+    parts: { url: string; offset: number; size: number }[]
+}
+
+const text = (value: unknown, max: number): value is string =>
+    typeof value === "string" && value.length > 0 && value.length <= max
+
+function destination(value: unknown, allowInsecure: boolean): value is string {
+    if (!text(value, 8192)) return false
+    try {
+        const url = new URL(value)
+        // Signed plan URLs are authenticated upload capabilities. Preserve their query, do not send bot auth, and never follow redirects
+        return (
+            (url.protocol === "https:" || (allowInsecure && url.protocol === "http:")) &&
+            url.username === "" &&
+            url.password === "" &&
+            url.hash === ""
+        )
+    } catch {
+        // allow-silent: An unparsable upload URL is rejected by the caller
+        return false
+    }
+}
+
+/** Validate the complete plan before dispatching any file bytes. Unknown response properties are discarded */
+export function decodeUploadPlans(
+    value: unknown,
+    files: readonly FilePart[],
+    allowInsecure: boolean,
+): UploadPlan[] | undefined {
+    if (!record(value) || !Array.isArray(value.attachments) || value.attachments.length !== files.length)
+        return undefined
+    const plans: UploadPlan[] = []
+    const keys = new Set<string>()
+    const urls = new Set<string>()
+    for (const file of files) {
+        const matches = value.attachments.filter((item) => record(item) && item.id === file.id)
+        if (matches.length !== 1) return undefined
+        const item = matches[0]!
+        if (
+            !record(item) ||
+            item.file_size !== file.size ||
+            !text(item.filename, 255) ||
+            // oxlint-disable-next-line no-control-regex -- rejects control characters in provider filenames
+            /[\x00-\x1f\x7f/\\]/.test(item.filename) ||
+            !text(item.content_type, 255) ||
+            !/^[\x20-\x7e]+$/.test(item.content_type) ||
+            !text(item.upload_filename, 4096) ||
+            keys.has(item.upload_filename)
+        )
+            return undefined
+        keys.add(item.upload_filename)
+        const plan: UploadPlan = {
+            id: file.id,
+            filename: item.filename,
+            contentType: item.content_type,
+            key: item.upload_filename,
+            parts: [],
+        }
+        if (item.upload_mode === "singlepart") {
+            if (!destination(item.upload_url, allowInsecure) || item.file_size > 10_485_760) return undefined
+            plan.parts.push({ url: item.upload_url, offset: 0, size: file.size })
+        } else if (item.upload_mode === "multipart") {
+            if (
+                !text(item.upload_id, 1024) ||
+                typeof item.part_size !== "number" ||
+                !Number.isSafeInteger(item.part_size) ||
+                item.part_size <= 0 ||
+                item.part_size > 52_428_800 ||
+                !Array.isArray(item.parts) ||
+                item.parts.length === 0 ||
+                item.parts.length > 10_000 ||
+                item.parts.length !== Math.ceil(file.size / item.part_size)
+            )
+                return undefined
+            plan.uploadId = item.upload_id
+            for (let index = 0; index < item.parts.length; index++) {
+                const part = item.parts[index]
+                if (!record(part) || part.part_number !== index + 1 || !destination(part.upload_url, allowInsecure))
+                    return undefined
+                const offset = index * item.part_size
+                plan.parts.push({
+                    url: part.upload_url,
+                    offset,
+                    size: Math.min(item.part_size, file.size - offset),
+                })
+            }
+        } else return undefined
+        for (const part of plan.parts) {
+            if (urls.has(part.url)) return undefined
+            urls.add(part.url)
+        }
+        plans.push(plan)
+    }
+    return plans
+}