@actana/sdk 0.2.2 → 0.3.2

package/dist/core-files-error-codes.js

@@ -0,0 +1,123 @@
+// The refusal vocabulary of the Core's file surface — one definition, for both
+// ends of the wire (#224).
+//
+// ## Why this file exists rather than a union in each package
+//
+// This union was written out twice, verbatim and in the same order: once in
+// `packages/core/src/core-files-routes.ts`, which is the side that *sends* the
+// codes, and once in `packages/sdk/src/core-files-http.ts`, which is the side
+// that *reads* them. The two agreed, member for member, the whole time they
+// existed — so nothing here is a repair. What made it worth a ticket is that
+// the two copies were not equally load-bearing, and the asymmetry ran the wrong
+// way round:
+//
+// - The Core's copy is **checked**. `Refusal` types every refusal the routes
+//   send, so a code outside the union is a compile error, and the two narrower
+//   lists inside that package — `TarRefusalCode` in `files-tar.ts` and
+//   `FileConfinementRefusal` in `files-confinement.ts` — are pinned as subsets
+//   by assignment. Inside the Core, a copy cannot drift.
+// - The SDK's copy was **not checked, deliberately**. Every use site widens it
+//   to `CoreFilesErrorCode | string`, because a client that meets a Core newer
+//   than itself has to survive a code it has never heard of. That widening is
+//   correct and it survives this change (see `core-files-http.ts`) — but it
+//   also means a member missing from the SDK's list was a type error nowhere.
+//
+// So the one place the copy could drift was the one place nothing would notice,
+// and the drift would not surface as a break. It would surface as two processes
+// disagreeing on a wire while each typechecks cleanly: the Core answers a code
+// the client cannot name, every consumer's `catch` still compiles because of the
+// `| string`, and the operator gets a refusal their tooling has no word for.
+//
+// That is not a hypothetical about this seam. #218/#219 is the same seam doing
+// exactly this: the SDK targeted `?list=1`, the Core served `/files/list`, each
+// side documented its choice at length, neither knew, and **both suites passed
+// the whole time** — because each proved itself against its own idea of the
+// other. And the review that raised this ticket produced the maintenance cost
+// while it was still running: the commit that added `root-entry-path`, the 22nd
+// member, had to edit both packages to do it, with nothing pointing the author
+// at the second file.
+//
+// ## Why the SDK owns it, and why that arrow is not upside-down
+//
+// The Core is the *server* answering these codes and it now imports their
+// definition from the *client* package. That reads backwards and is the same
+// trade [ADR 0025](../../../docs/adr/0025-the-protocol-ships-with-the-client.md)
+// already made for the core-link frames, for the same reason: **what the Core
+// depends on is the protocol, not the client.** D2 rules that arrow is not a
+// layering violation, and D3 states the rule this file exists to satisfy —
+// "there is exactly one definition of every frame type, and a mirror is never
+// the answer", because a mirror "does not fail; it disagrees, at runtime, on a
+// wire, between two processes that each believe they are correct."
+//
+// ADR 0025 D1 scoped that record to `core-link-frames.ts`, so this union sat
+// just outside its subject. #224 moves the scope rather than re-deriving the
+// argument: D2's rule now names this module too, and the ADR's consequences say
+// so, so the next reviewer meets the widened rule where the rule lives.
+//
+// ## Why a module of its own, and not `core-files-http.ts`
+//
+// `core-files-http.ts` is a transport: it imports `undici` and builds
+// dispatchers. An `import type` erases, so parking the union there would have
+// created no runtime edge for the Core either — but it would have pointed the
+// Core's source at a file full of client machinery to read a vocabulary, and
+// D2's rule is only reviewable if what the Core may import is a module a
+// reviewer can see holds nothing else. This file imports nothing, exactly as
+// `core-link-frames.ts` imports nothing, and that is the property that makes it
+// safe to depend on from the server.
+//
+// **It is public API.** `packages/sdk/package.json` exports `./*`, so this is
+// the published subpath `@actana/sdk/core-files-error-codes` on the next
+// publish. That is a release decision and it is taken here deliberately rather
+// than fallen into: the refusal vocabulary is precisely the thing a third party
+// writing a `catch` wants to type against, so it is better named than hidden.
+// `core-files-http.ts` re-exports the type as well, so the specifier that
+// already worked keeps working and nothing published moves.
+//
+// ## Why the codes are a value and not only a type
+//
+// A union of string literals erases at compile time, which leaves nothing for a
+// test to read. The list below is therefore a `const` tuple and the type is
+// derived from it, so the vocabulary is enumerable at runtime and the *third*
+// copy of it — the operator-facing table in `docs/external-api.md` — can be
+// pinned to this one by a test rather than by somebody remembering.
+// `core-files-error-codes.test.ts` is that test. Nothing shipped imports the
+// array, and nothing has to: `import type` erases in the Core's bundle, so the
+// server still carries no runtime edge into this package.
+/**
+ * Every machine-readable refusal code the Core's file routes can answer with.
+ *
+ * Order is not meaning — nothing reads these by index. Keep it grouped as it is
+ * (request, then path, then transfer, then tar entry, then I/O) because that is
+ * the order `docs/external-api.md` explains them in, and two lists a reader
+ * compares by eye are easier to compare when they run the same way.
+ *
+ * **Adding one is a one-file change**: append it here, and the Core's `Refusal`
+ * type and the SDK's error classes both accept it with no further edit. The
+ * docs table is the one copy left, and it is not a copy you can forget —
+ * `core-files-error-codes.test.ts` goes red until it names the new code too.
+ */
+export const CORE_FILES_ERROR_CODES = [
+    "unauthorized",
+    "not-found",
+    "project-not-found",
+    "method-not-allowed",
+    "bad-request",
+    "absolute-path",
+    "dot-dot-segment",
+    "outside-project-root",
+    "malformed-path",
+    "transfer-in-progress",
+    "insufficient-storage",
+    "corrupt-archive",
+    "absolute-entry-path",
+    "dot-dot-entry-path",
+    "root-entry-path",
+    "entry-outside-root",
+    "unsupported-entry-type",
+    "hardlink-outside-root",
+    "symlink-outside-root",
+    "directory-in-the-way",
+    "write-failed",
+    "read-failed",
+];
+//# sourceMappingURL=core-files-error-codes.js.map

package/dist/core-files-error-codes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-files-error-codes.js","sourceRoot":"","sources":["../src/core-files-error-codes.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,2BAA2B;AAC3B,EAAE;AACF,8DAA8D;AAC9D,EAAE;AACF,4EAA4E;AAC5E,+EAA+E;AAC/E,8EAA8E;AAC9E,4EAA4E;AAC5E,6EAA6E;AAC7E,gFAAgF;AAChF,aAAa;AACb,EAAE;AACF,6EAA6E;AAC7E,+EAA+E;AAC/E,uEAAuE;AACvE,+EAA+E;AAC/E,yDAAyD;AACzD,+EAA+E;AAC/E,+EAA+E;AAC/E,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAC9E,EAAE;AACF,gFAAgF;AAChF,gFAAgF;AAChF,+EAA+E;AAC/E,iFAAiF;AACjF,6EAA6E;AAC7E,EAAE;AACF,+EAA+E;AAC/E,gFAAgF;AAChF,+EAA+E;AAC/E,4EAA4E;AAC5E,8EAA8E;AAC9E,gFAAgF;AAChF,+EAA+E;AAC/E,sBAAsB;AACtB,EAAE;AACF,gEAAgE;AAChE,EAAE;AACF,0EAA0E;AAC1E,6EAA6E;AAC7E,iFAAiF;AACjF,8EAA8E;AAC9E,6EAA6E;AAC7E,2EAA2E;AAC3E,8EAA8E;AAC9E,+EAA+E;AAC/E,mEAAmE;AACnE,EAAE;AACF,6EAA6E;AAC7E,6EAA6E;AAC7E,gFAAgF;AAChF,wEAAwE;AACxE,EAAE;AACF,2DAA2D;AAC3D,EAAE;AACF,sEAAsE;AACtE,8EAA8E;AAC9E,8EAA8E;AAC9E,6EAA6E;AAC7E,yEAAyE;AACzE,6EAA6E;AAC7E,gFAAgF;AAChF,qCAAqC;AACrC,EAAE;AACF,8EAA8E;AAC9E,yEAAyE;AACzE,+EAA+E;AAC/E,gFAAgF;AAChF,8EAA8E;AAC9E,0EAA0E;AAC1E,4DAA4D;AAC5D,EAAE;AACF,mDAAmD;AACnD,EAAE;AACF,gFAAgF;AAChF,4EAA4E;AAC5E,8EAA8E;AAC9E,4EAA4E;AAC5E,oEAAoE;AACpE,6EAA6E;AAC7E,+EAA+E;AAC/E,0DAA0D;AAE1D;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,cAAc;IACd,WAAW;IACX,mBAAmB;IACnB,oBAAoB;IACpB,aAAa;IACb,eAAe;IACf,iBAAiB;IACjB,sBAAsB;IACtB,gBAAgB;IAChB,sBAAsB;IACtB,sBAAsB;IACtB,iBAAiB;IACjB,qBAAqB;IACrB,oBAAoB;IACpB,iBAAiB;IACjB,oBAAoB;IACpB,wBAAwB;IACxB,uBAAuB;IACvB,sBAAsB;IACtB,sBAAsB;IACtB,cAAc;IACd,aAAa;CACL,CAAC"}

package/dist/core-files-http.d.ts

@@ -0,0 +1,119 @@
+import type { CoreFilesErrorCode } from "./core-files-error-codes.ts";
+import type { CoreLinkTlsMaterial } from "./core-link-socket.ts";
+export type { CoreFilesErrorCode } from "./core-files-error-codes.ts";
+/** Base class for everything `project.files.*` throws, so one `catch` can name it. */
+export declare class CoreFilesError extends Error {
+    constructor(message: string);
+}
+/**
+ * This Core has no file surface (F9, #165's `files` capability).
+ *
+ * Thrown *before any request goes out*, which is the point: a client that
+ * called the route anyway would read a `404` off a Core that simply predates the
+ * surface and report it as an outage. The `reason` is prose for an operator
+ * because "unavailable" on its own sends somebody to check their network.
+ */
+export declare class CoreFilesUnavailableError extends CoreFilesError {
+    readonly reason: string;
+    constructor(reason: string);
+}
+/**
+ * A refusal with a status line: the Core answered, and said no.
+ *
+ * ## `CoreFilesErrorCode | string` is the type, and it stays that way
+ *
+ * Stated here rather than left to be inferred, because it looks like a loose
+ * type somebody forgot to tighten and it is the opposite (#224). A client is
+ * routinely older than the Core it dials: this package is published, an
+ * operator upgrades a Core, and the next release of that Core may answer a
+ * refusal code this build of the SDK has never heard of. Typing `code` as the
+ * closed union would make the honest handling of that — reading the code the
+ * Core actually sent — a cast at every call site, and would invite a client to
+ * `switch` exhaustively over a vocabulary it does not own the far end of.
+ *
+ * So the union is autocomplete and documentation, and `| string` is the truth
+ * about the wire. Narrowing this later is a **decision** — it means declaring
+ * that a client may refuse to name what its Core told it — and not a cleanup
+ * for a passing reader to do.
+ *
+ * Note what this therefore does *not* buy, so the guarantee is not overstated:
+ * one definition (see `core-files-error-codes.ts`) removes the drift where the
+ * SDK lists fewer codes than the Core sends. It cannot remove the widening's
+ * own blind spot, because that is not drift — it is the wire being older or
+ * newer than the reader, which is a fact about deployments rather than about
+ * this repository.
+ */
+export declare class CoreFilesRequestError extends CoreFilesError {
+    readonly status: number;
+    readonly code: CoreFilesErrorCode | string;
+    constructor(status: number, code: CoreFilesErrorCode | string, message: string);
+}
+/**
+ * The one-write-per-Project rule (F8), as an error and **never as a retry**.
+ *
+ * `409 transfer-in-progress` is a conflict a human has to resolve — some other
+ * transfer is running on this Project right now, possibly a multi-gigabyte one
+ * with twenty minutes left. A client that retried under the hood would convert
+ * the Core's clear, immediate refusal into a hang with no output, which is
+ * strictly worse than the error: the operator loses both the reason and the
+ * chance to decide. So nothing in this package sleeps, backs off or re-sends —
+ * this class *is* the handling, and the decision is the caller's.
+ *
+ * `directory-in-the-way` shares the status and the same rule: it is a refusal
+ * to delete a tree, and it will still be a directory on the next attempt.
+ */
+export declare class CoreFilesConflictError extends CoreFilesRequestError {
+    constructor(status: number, code: CoreFilesErrorCode | string, message: string);
+}
+/**
+ * A failure that arrived as the **last line of a progress stream** rather than
+ * as a status code, because the `200` was spent on the first entry.
+ *
+ * This is why the progress stream is NDJSON and not a JSON document: a document
+ * would have to be well-formed to be read at all, and this one stops in the
+ * middle by design.
+ */
+export declare class CoreFilesStreamError extends CoreFilesError {
+    readonly code: CoreFilesErrorCode | string;
+    constructor(code: CoreFilesErrorCode | string, message: string);
+}
+/** One request, in the terms this surface actually uses. */
+export type CoreFilesRequest = {
+    method: "GET" | "HEAD" | "PUT";
+    url: string;
+    headers: Record<string, string>;
+    /** A stream, never a buffer — see {@link CoreFiles.upload}. */
+    body?: ReadableStream<Uint8Array> | null;
+    signal?: AbortSignal;
+};
+/**
+ * How a file request is actually sent.
+ *
+ * Injected rather than reached for, on the same terms as
+ * {@link CoreLinkSocketFactory}: it is what lets a suite drive this surface
+ * over a plain loopback server, and what lets a runtime with its own
+ * dispatcher — a proxy, a recorder, a browser — supply one. The default is
+ * {@link createCoreFilesFetch}.
+ */
+export type CoreFilesFetch = (req: CoreFilesRequest) => Promise<Response>;
+/**
+ * The default sender: `fetch`, with the client certificate carried in on a
+ * dispatcher.
+ *
+ * The `Agent` is built **once, lazily, and only when there is TLS material** —
+ * a `http://` loopback Core needs no dispatcher, and building one per request
+ * would open a fresh connection pool for every upload.
+ */
+export declare function createCoreFilesFetch(tls: CoreLinkTlsMaterial | null): CoreFilesFetch;
+/**
+ * Turn a non-2xx answer into the right error class, reading the `code` beside
+ * the prose rather than the prose.
+ *
+ * A client branches on `code` because a message is a sentence somebody will
+ * reword — and `transfer-in-progress` in particular *has* to stay
+ * distinguishable (F8). The body is read to completion here, and only here: a
+ * refusal body is a short JSON object, which is why buffering it does not
+ * violate the streaming rule the success paths keep.
+ */
+export declare function refusalFrom(res: Response, what: string): Promise<CoreFilesRequestError>;
+//# sourceMappingURL=core-files-http.d.ts.map

package/dist/core-files-http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-files-http.d.ts","sourceRoot":"","sources":["../src/core-files-http.ts"],"names":[],"mappings":"AA2DA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AACtE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AASjE,YAAY,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAEtE,sFAAsF;AACtF,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;GAOG;AACH,qBAAa,yBAA0B,SAAQ,cAAc;IAC3D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;gBAEZ,MAAM,EAAE,MAAM;CAK3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,qBAAsB,SAAQ,cAAc;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAAC;gBAE/B,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM;CAM/E;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,sBAAuB,SAAQ,qBAAqB;gBACnD,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM;CAI/E;AAED;;;;;;;GAOG;AACH,qBAAa,oBAAqB,SAAQ,cAAc;IACtD,QAAQ,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAAC;gBAE/B,IAAI,EAAE,kBAAkB,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM;CAK/D;AAED,4DAA4D;AAC5D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;IAC/B,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,+DAA+D;IAC/D,IAAI,CAAC,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;IACzC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAE1E;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,mBAAmB,GAAG,IAAI,GAAG,cAAc,CA8BpF;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAe7F"}

package/dist/core-files-http.js

@@ -0,0 +1,223 @@
+// The SDK's first HTTPS surface (#167, F12) — how a file request reaches a
+// Core, and what a refusal from one means.
+//
+// Everything in this package before this module spoke one protocol: the
+// core-link WebSocket. File bytes deliberately do not cross it (ADR 0028), so
+// `project.files.*` dials the *same* mTLS server on the *same* port with the
+// *same* certificate and bearer, over HTTP instead of a WebSocket upgrade.
+// `CoreConnection.httpsBaseUrl` has named that origin since phase 1 precisely
+// so this module would not be the thing that changed a published shape.
+//
+// ## The `fetch` shape is frozen, not chosen here
+//
+// The phase-1 spike (#151, PR 189) settled how a client certificate reaches
+// `fetch` and its verdict is reused verbatim rather than rediscovered:
+//
+//     const agent = new Agent({ connect: { ca, cert, key } });
+//     await fetch(url, { dispatcher: agent });
+//
+// **`fetch` is undici and ignores `options.cert` / `options.key`.** There is no
+// option bag on `fetch` that reaches TLS at all — the dispatcher is the only
+// seam. A client built the `https.request` way silently makes an *anonymous*
+// connection, which a Core with `requestCert: true, rejectUnauthorized: true`
+// refuses at the handshake with an error that names no certificate; that is a
+// long debugging session, and it is the whole reason the spike exists. The
+// spike's leg 2b is the control that makes the shape mean anything: the same
+// `fetch` through a CA-only `Agent` is refused at the TLS layer. D12 also held
+// — both legs pass on Node 22 — so this package's `engines: ">=22"` stands.
+//
+// ### One thing the spike could not have found, and this had to
+//
+// **The `fetch` above is undici's own, not the global one**, and the two are
+// not interchangeable. Node embeds a *copy* of undici for its global `fetch`,
+// and a `Dispatcher` only satisfies the implementation it came from: handing a
+// dispatcher from the `undici` package to Node 24's built-in `fetch` fails with
+// `InvalidArgumentError: invalid onRequestStart method`, because undici 8
+// changed the handler interface that the embedded copy still expects. The
+// spike never met this — it loaded `ws` and `undici` as a matching pair from
+// one directory and used the global `fetch`, which happened to agree at those
+// versions.
+//
+// Importing both halves from the same package is what makes that class of skew
+// impossible rather than merely absent today: this package's `fetch` and its
+// `Agent` are the same implementation, whatever Node bundles underneath. The
+// frozen finding is untouched — the dispatcher is still the only seam, and the
+// CA-only control still has to be refused — and `core-files-mtls.test.ts` holds
+// both against a real handshake.
+//
+// ## Why `undici` is this package's second dependency
+//
+// `ws` is here because Node's global `WebSocket` cannot present a client
+// certificate. `undici` is here for the identical reason one layer up: Node's
+// global `fetch` cannot either, and the `Agent` that lets it is not exposed by
+// any builtin. It is a public package on the registry, so unlike `@actana/shared`
+// it is resolvable by everyone who installs this SDK — the boundary ADR 0025 D4
+// draws is around *private workspace* packages, not around dependencies as such.
+// A caller who never dials `https://` never constructs an `Agent`: the dispatcher
+// is built lazily, on the first request that needs one.
+import { Agent, fetch as undiciFetch } from "undici";
+/** Base class for everything `project.files.*` throws, so one `catch` can name it. */
+export class CoreFilesError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CoreFilesError";
+    }
+}
+/**
+ * This Core has no file surface (F9, #165's `files` capability).
+ *
+ * Thrown *before any request goes out*, which is the point: a client that
+ * called the route anyway would read a `404` off a Core that simply predates the
+ * surface and report it as an outage. The `reason` is prose for an operator
+ * because "unavailable" on its own sends somebody to check their network.
+ */
+export class CoreFilesUnavailableError extends CoreFilesError {
+    reason;
+    constructor(reason) {
+        super(reason);
+        this.name = "CoreFilesUnavailableError";
+        this.reason = reason;
+    }
+}
+/**
+ * A refusal with a status line: the Core answered, and said no.
+ *
+ * ## `CoreFilesErrorCode | string` is the type, and it stays that way
+ *
+ * Stated here rather than left to be inferred, because it looks like a loose
+ * type somebody forgot to tighten and it is the opposite (#224). A client is
+ * routinely older than the Core it dials: this package is published, an
+ * operator upgrades a Core, and the next release of that Core may answer a
+ * refusal code this build of the SDK has never heard of. Typing `code` as the
+ * closed union would make the honest handling of that — reading the code the
+ * Core actually sent — a cast at every call site, and would invite a client to
+ * `switch` exhaustively over a vocabulary it does not own the far end of.
+ *
+ * So the union is autocomplete and documentation, and `| string` is the truth
+ * about the wire. Narrowing this later is a **decision** — it means declaring
+ * that a client may refuse to name what its Core told it — and not a cleanup
+ * for a passing reader to do.
+ *
+ * Note what this therefore does *not* buy, so the guarantee is not overstated:
+ * one definition (see `core-files-error-codes.ts`) removes the drift where the
+ * SDK lists fewer codes than the Core sends. It cannot remove the widening's
+ * own blind spot, because that is not drift — it is the wire being older or
+ * newer than the reader, which is a fact about deployments rather than about
+ * this repository.
+ */
+export class CoreFilesRequestError extends CoreFilesError {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.name = "CoreFilesRequestError";
+        this.status = status;
+        this.code = code;
+    }
+}
+/**
+ * The one-write-per-Project rule (F8), as an error and **never as a retry**.
+ *
+ * `409 transfer-in-progress` is a conflict a human has to resolve — some other
+ * transfer is running on this Project right now, possibly a multi-gigabyte one
+ * with twenty minutes left. A client that retried under the hood would convert
+ * the Core's clear, immediate refusal into a hang with no output, which is
+ * strictly worse than the error: the operator loses both the reason and the
+ * chance to decide. So nothing in this package sleeps, backs off or re-sends —
+ * this class *is* the handling, and the decision is the caller's.
+ *
+ * `directory-in-the-way` shares the status and the same rule: it is a refusal
+ * to delete a tree, and it will still be a directory on the next attempt.
+ */
+export class CoreFilesConflictError extends CoreFilesRequestError {
+    constructor(status, code, message) {
+        super(status, code, message);
+        this.name = "CoreFilesConflictError";
+    }
+}
+/**
+ * A failure that arrived as the **last line of a progress stream** rather than
+ * as a status code, because the `200` was spent on the first entry.
+ *
+ * This is why the progress stream is NDJSON and not a JSON document: a document
+ * would have to be well-formed to be read at all, and this one stops in the
+ * middle by design.
+ */
+export class CoreFilesStreamError extends CoreFilesError {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "CoreFilesStreamError";
+        this.code = code;
+    }
+}
+/**
+ * The default sender: `fetch`, with the client certificate carried in on a
+ * dispatcher.
+ *
+ * The `Agent` is built **once, lazily, and only when there is TLS material** —
+ * a `http://` loopback Core needs no dispatcher, and building one per request
+ * would open a fresh connection pool for every upload.
+ */
+export function createCoreFilesFetch(tls) {
+    let dispatcher = null;
+    return async (req) => {
+        if (tls && !dispatcher) {
+            dispatcher = new Agent({ connect: { ca: tls.ca, cert: tls.cert, key: tls.key } });
+        }
+        // `duplex: "half"` is mandatory for a streamed request body and is not a
+        // detail that can be left out: without it `fetch` rejects the body outright,
+        // which would take this surface straight back to buffering an upload in
+        // memory — the one thing #167 exists to not do.
+        //
+        // The casts are the type-level shadow of the same two-copies problem the
+        // header describes: `@types/node` declares the global `fetch` with its own
+        // bundled `undici-types`, and this module deliberately uses the real
+        // package's `fetch` instead. The two `Response` and `RequestInit`
+        // declarations are structurally near-identical and neither is wrong — they
+        // are simply not the same declaration. Everything this package reads off a
+        // response (`ok`, `status`, `headers.get`, `json`, `body`) is common to
+        // both, and the global `Response` is what callers and tests hold, so that
+        // is the type this surface promises.
+        const init = {
+            method: req.method,
+            headers: req.headers,
+            ...(req.body ? { body: req.body, duplex: "half" } : {}),
+            ...(req.signal ? { signal: req.signal } : {}),
+            ...(dispatcher ? { dispatcher } : {}),
+        };
+        const res = await undiciFetch(req.url, init);
+        return res;
+    };
+}
+/**
+ * Turn a non-2xx answer into the right error class, reading the `code` beside
+ * the prose rather than the prose.
+ *
+ * A client branches on `code` because a message is a sentence somebody will
+ * reword — and `transfer-in-progress` in particular *has* to stay
+ * distinguishable (F8). The body is read to completion here, and only here: a
+ * refusal body is a short JSON object, which is why buffering it does not
+ * violate the streaming rule the success paths keep.
+ */
+export async function refusalFrom(res, what) {
+    let code = "";
+    let message = "";
+    try {
+        const body = (await res.json());
+        if (typeof body.code === "string")
+            code = body.code;
+        if (typeof body.error === "string")
+            message = body.error;
+    }
+    catch {
+        // A refusal that is not the Core's JSON shape — a proxy's HTML error page,
+        // a truncated body. Say what is actually known rather than inventing a code.
+    }
+    const described = message || `${what} was refused with HTTP ${res.status}`;
+    const withCode = code ? `${described} (${code})` : described;
+    if (res.status === 409)
+        return new CoreFilesConflictError(res.status, code || "conflict", withCode);
+    return new CoreFilesRequestError(res.status, code || `http-${res.status}`, withCode);
+}
+//# sourceMappingURL=core-files-http.js.map

package/dist/core-files-http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-files-http.js","sourceRoot":"","sources":["../src/core-files-http.ts"],"names":[],"mappings":"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"}