@dmgnr/dcdn 0.1.0

package/README.md

@@ -0,0 +1,30 @@
+# @dmgnr/dcdn
+
+Small, conservative TypeScript client for DCDN. It works with Bun and modern Node `fetch`, and keeps canonical bearer APIs separate from the S3-shaped Basic-auth API.
+
+```ts
+import { DcdnClient, bytesRange } from '@dmgnr/dcdn';
+
+const dcdn = DcdnClient({ baseUrl: 'https://dcdn.example', token: process.env.DCDN_TOKEN });
+const file = dcdn.file('images/logo.png');
+const response = await file.get();
+await Bun.write('logo.png', await response.bytes());
+await file.put(await Bun.file('new-logo.png').arrayBuffer());
+
+for await (const path of dcdn.files.list({ prefix: 'images/' })) console.log(path);
+```
+
+S3-shaped access uses Basic auth and has ListV2 pagination:
+
+```ts
+const baseUrl = process.env.DCDN_BASE_URL ?? 'https://dcdn.example';
+const password = process.env.DCDN_PASSWORD ?? 'change-me';
+const bucket = DcdnClient({ baseUrl, basicAuth: { username: 'dcdn', password } }).bucket('media');
+const object = bucket.object('photos/one.jpg');
+const image = await object.get({ range: bytesRange({ start: 0, end: 1023 }) });
+for await (const entry of bucket.list({ delimiter: '/' })) console.log(entry);
+```
+
+GET/HEAD/list retry transient network and HTTP failures with bounded exponential full jitter. PUT retries are off by default: enable them only for replayable bodies (strings, bytes, `Blob`, `ArrayBuffer`) and remember that a timeout can leave an ambiguous write on the server. Stream failures after headers are never silently restarted.
+
+The service provides local durable acknowledgement with eventual cross-node consistency. Ranges are limited by the server configuration (64 MiB by default). This package does not implement rename, SigV4, multipart, versioning, ACLs, or other unsupported S3 features.

package/dist/index.d.ts

@@ -0,0 +1,181 @@
+export type FetchLike = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+export type DcdnBody = BodyInit | AsyncIterable<Uint8Array>;
+export type ReplayableBody = string | Blob | ArrayBuffer | ArrayBufferView<ArrayBufferLike>;
+export type BodySource = DcdnBody | (() => DcdnBody);
+export interface BasicAuth {
+    username: string;
+    password: string;
+}
+export interface RetryOptions {
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    put?: boolean;
+    random?: () => number;
+}
+export interface DcdnClientOptions {
+    baseUrl: string | URL;
+    token?: string;
+    basicAuth?: BasicAuth;
+    fetch?: FetchLike;
+    timeoutMs?: number;
+    retry?: RetryOptions | false;
+    userAgent?: string;
+}
+export interface RequestOptions {
+    signal?: AbortSignal;
+    headers?: HeadersInit;
+    range?: ByteRange | string;
+    ifMatch?: string;
+    ifNoneMatch?: string;
+}
+export interface PutOptions extends RequestOptions {
+    contentType?: string;
+    contentMD5?: string;
+    retry?: boolean;
+}
+export interface ByteRange {
+    start?: number;
+    end?: number;
+    suffix?: number;
+}
+export interface DcdnMetadata {
+    status: number;
+    headers: Headers;
+    size?: number;
+    contentType?: string;
+    etag?: string;
+    lastModified?: Date;
+    range?: string;
+}
+export interface DcdnResponse extends DcdnMetadata {
+    body: ReadableStream<Uint8Array> | null;
+    bytes(): Promise<Uint8Array>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+    text(): Promise<string>;
+}
+export interface CanonicalListPage {
+    entries: string[];
+    continuationToken?: string;
+}
+export interface S3ObjectMetadata extends DcdnMetadata {
+    key: string;
+}
+export interface S3ObjectEntry {
+    key: string;
+    size: number;
+    etag?: string;
+    lastModified?: Date;
+}
+export interface S3ListPage {
+    bucket: string;
+    prefix: string;
+    keyCount: number;
+    maxKeys: number;
+    isTruncated: boolean;
+    nextContinuationToken?: string;
+    objects: S3ObjectEntry[];
+    commonPrefixes: string[];
+}
+export interface CanonicalListOptions {
+    prefix?: string;
+    limit?: number;
+    signal?: AbortSignal;
+}
+export interface S3ListOptions {
+    prefix?: string;
+    delimiter?: '/';
+    maxKeys?: number;
+    continuationToken?: string;
+    startAfter?: string;
+    encodingType?: 'url';
+    signal?: AbortSignal;
+}
+export type DcdnErrorCode = 'HTTP_ERROR' | 'NETWORK_ERROR' | 'ABORTED' | 'TIMEOUT' | 'INVALID_INPUT' | 'STREAM_ERROR';
+export interface S3ErrorInfo {
+    code?: string;
+    requestId?: string;
+    hostId?: string;
+}
+export declare class DcdnError extends Error {
+    readonly status?: number;
+    readonly code: DcdnErrorCode;
+    readonly retryable: boolean;
+    readonly attempt: number;
+    readonly cause?: unknown;
+    readonly s3?: S3ErrorInfo;
+    constructor(message: string, fields: {
+        code: DcdnErrorCode;
+        status?: number;
+        retryable?: boolean;
+        attempt?: number;
+        cause?: unknown;
+        s3?: S3ErrorInfo;
+    });
+}
+export declare function bytesRange(range: ByteRange): string;
+export declare const byteRange: typeof bytesRange;
+type InternalOptions = DcdnClientOptions & {
+    fetcher: FetchLike;
+    base: URL;
+    retry: RetryOptions;
+};
+interface RequestLease {
+    body: ReadableStream<Uint8Array> | null;
+    release(): void;
+}
+declare class ClientCore {
+    protected readonly options: InternalOptions;
+    constructor(options: InternalOptions);
+    protected request(method: string, path: string, init?: RequestInit, kind?: 'read' | 'write', allowWriteRetry?: boolean, bodyFactory?: () => DcdnBody): Promise<{
+        response: Response;
+        attempt: number;
+        lease: RequestLease;
+    }>;
+}
+declare class Resource extends ClientCore {
+    protected view(response: Response, attempt: number, body?: ReadableStream<Uint8Array<ArrayBufferLike>> | null): DcdnResponse;
+    protected call(method: string, path: string, options?: RequestOptions, body?: BodySource, kind?: 'read' | 'write', allowWriteRetry?: boolean): Promise<DcdnResponse>;
+}
+declare class CanonicalFile extends Resource {
+    private readonly path;
+    constructor(options: InternalOptions, path: string);
+    get(options?: RequestOptions): Promise<DcdnResponse>;
+    head(options?: RequestOptions): Promise<DcdnResponse>;
+    put(body: BodySource, options?: PutOptions): Promise<DcdnResponse>;
+    delete(options?: RequestOptions): Promise<void>;
+}
+declare class CanonicalFiles extends ClientCore {
+    listPage(options?: CanonicalListOptions, token?: string): Promise<{
+        entries: string[];
+        continuationToken: string | undefined;
+    }>;
+    list(options?: CanonicalListOptions): AsyncGenerator<string, void, unknown>;
+}
+declare class S3Object extends Resource {
+    private readonly bucketName;
+    private readonly objectKey;
+    constructor(options: InternalOptions, bucketName: string, objectKey: string);
+    private path;
+    get(options?: RequestOptions): Promise<DcdnResponse>;
+    head(options?: RequestOptions): Promise<DcdnResponse>;
+    put(body: BodySource, options?: PutOptions): Promise<{
+        etag: string | undefined;
+        response: DcdnResponse;
+    }>;
+    delete(options?: RequestOptions): Promise<void>;
+}
+declare class S3Bucket extends ClientCore {
+    readonly name: string;
+    constructor(options: InternalOptions, name: string);
+    object(key: string): S3Object;
+    listPage(options?: S3ListOptions, token?: string): Promise<S3ListPage>;
+    list(options?: S3ListOptions): AsyncGenerator<string | S3ObjectEntry, void, unknown>;
+}
+export interface DcdnClientInstance {
+    file(path: string): CanonicalFile;
+    files: CanonicalFiles;
+    bucket(name: string): S3Bucket;
+}
+export declare function DcdnClient(input: DcdnClientOptions): DcdnClientInstance;
+export {};

package/dist/index.js

@@ -0,0 +1,585 @@
+// @bun
+// src/index.ts
+class DcdnError extends Error {
+  status;
+  code;
+  retryable;
+  attempt;
+  cause;
+  s3;
+  constructor(message, fields) {
+    super(message, { cause: fields.cause });
+    this.name = "DcdnError";
+    this.code = fields.code;
+    this.status = fields.status;
+    this.retryable = fields.retryable ?? false;
+    this.attempt = fields.attempt ?? 1;
+    this.cause = fields.cause;
+    this.s3 = fields.s3;
+  }
+}
+function bytesRange(range) {
+  if (range.suffix !== undefined)
+    return `bytes=-${positiveInt(range.suffix, "suffix")}`;
+  if (range.start === undefined)
+    throw invalid("range start is required");
+  if (range.start < 0 || !Number.isInteger(range.start))
+    throw invalid("range start must be a non-negative integer");
+  if (range.end !== undefined && (range.end < range.start || !Number.isInteger(range.end)))
+    throw invalid("range end is invalid");
+  return `bytes=${range.start}-${range.end ?? ""}`;
+}
+var byteRange = bytesRange;
+var retryStatuses = new Set([408, 425, 429, 500, 502, 503, 504]);
+
+class ResponseView {
+  response;
+  attempt;
+  stream;
+  constructor(response, attempt, stream) {
+    this.response = response;
+    this.attempt = attempt;
+    this.stream = stream;
+  }
+  get status() {
+    return this.response.status;
+  }
+  get headers() {
+    return this.response.headers;
+  }
+  get body() {
+    return this.stream;
+  }
+  async bytes() {
+    return readBody(this.stream, this.attempt, (v) => new Uint8Array(v));
+  }
+  async arrayBuffer() {
+    return readBody(this.stream, this.attempt, (v) => v.buffer.slice(v.byteOffset, v.byteOffset + v.byteLength));
+  }
+  async text() {
+    return readBody(this.stream, this.attempt, (v) => new TextDecoder().decode(v));
+  }
+}
+
+class ClientCore {
+  options;
+  constructor(options) {
+    this.options = options;
+  }
+  async request(method, path, init = {}, kind = "read", allowWriteRetry = false, bodyFactory) {
+    if (init.signal?.aborted)
+      throw new DcdnError("request aborted", { code: "ABORTED", cause: init.signal.reason });
+    const url = new URL(path.replace(/^\//, ""), this.options.base);
+    const headers = new Headers(init.headers);
+    if (this.options.userAgent)
+      headers.set("user-agent", this.options.userAgent);
+    const s3Request = path.startsWith("/s3/");
+    if (!s3Request && this.options.token && !headers.has("authorization"))
+      headers.set("authorization", `Bearer ${this.options.token}`);
+    if (s3Request && this.options.basicAuth && !headers.has("authorization")) {
+      const encoded = btoa(`${this.options.basicAuth.username}:${this.options.basicAuth.password}`);
+      headers.set("authorization", `Basic ${encoded}`);
+    }
+    const attempts = kind === "read" ? this.options.retry.maxAttempts ?? 3 : allowWriteRetry && this.options.retry.put ? this.options.retry.maxAttempts ?? 3 : 1;
+    const deadline = Date.now() + (this.options.timeoutMs ?? 30000);
+    let attempt = 0;
+    while (true) {
+      attempt++;
+      const remaining = deadline - Date.now();
+      if (remaining <= 0)
+        throw new DcdnError("request timed out", { code: "TIMEOUT", attempt, retryable: false });
+      const controller = new AbortController;
+      const onAbort = () => controller.abort(init.signal?.reason);
+      init.signal?.addEventListener("abort", onAbort, { once: true });
+      const timer = setTimeout(() => controller.abort(new Error("dcdn timeout")), remaining);
+      let returned = false;
+      try {
+        const requestInit = { ...init, body: bodyFactory?.(), method, headers, signal: controller.signal };
+        if (requestInit.body && (requestInit.body instanceof ReadableStream || typeof requestInit.body === "object" && (Symbol.asyncIterator in requestInit.body)))
+          requestInit.duplex = "half";
+        const response = await this.options.fetcher(url, requestInit);
+        if (response.ok || response.status === 304 || response.status === 204) {
+          returned = true;
+          return { response, attempt, lease: bodyLease(response, controller, init.signal ?? undefined, timer, onAbort, attempt) };
+        }
+        const retryable = retryStatuses.has(response.status) && attempt < attempts && (method !== "PUT" || allowWriteRetry);
+        if (retryable) {
+          await cancelResponseBody(response);
+          await waitRetry(response.headers, attempt, deadline, this.options.retry, init.signal ?? undefined);
+          continue;
+        }
+        throw await responseError(response, attempt);
+      } catch (error) {
+        if (error instanceof DcdnError) {
+          throw error;
+        }
+        const callerAborted = init.signal?.aborted;
+        const timedOut = controller.signal.aborted && !callerAborted;
+        if (callerAborted)
+          throw new DcdnError("request aborted", { code: "ABORTED", attempt, cause: error });
+        if (timedOut)
+          throw new DcdnError("request timed out", { code: "TIMEOUT", attempt, cause: error });
+        if (attempt >= attempts)
+          throw new DcdnError("network request failed", { code: "NETWORK_ERROR", attempt, retryable: true, cause: error });
+        await waitRetry(undefined, attempt, deadline, this.options.retry, init.signal ?? undefined);
+      } finally {
+        if (!returned) {
+          clearTimeout(timer);
+          init.signal?.removeEventListener("abort", onAbort);
+        }
+      }
+    }
+  }
+}
+
+class Resource extends ClientCore {
+  view(response, attempt, body = response.body) {
+    const range = response.headers.get("content-range") ?? undefined;
+    const view = new ResponseView(response, attempt, body);
+    return { ...metadata(response, range), body: view.body, bytes: () => view.bytes(), arrayBuffer: () => view.arrayBuffer(), text: () => view.text() };
+  }
+  async call(method, path, options = {}, body, kind = "read", allowWriteRetry = false) {
+    const headers = new Headers(options.headers);
+    if (options.range)
+      headers.set("range", typeof options.range === "string" ? options.range : bytesRange(options.range));
+    if (options.ifMatch)
+      headers.set("if-match", normalizeEtagInput(options.ifMatch));
+    if (options.ifNoneMatch)
+      headers.set("if-none-match", normalizeEtagInput(options.ifNoneMatch));
+    const source = typeof body === "function" ? body : () => body;
+    const result = await this.request(method, path, { headers, signal: options.signal }, kind, allowWriteRetry, source);
+    return this.view(result.response, result.attempt, result.lease.body);
+  }
+}
+
+class CanonicalFile extends Resource {
+  path;
+  constructor(options, path) {
+    super(options);
+    this.path = path;
+  }
+  get(options) {
+    return this.call("GET", `/__/files/${pathSegments(this.path)}`, options);
+  }
+  head(options) {
+    return this.call("HEAD", `/__/files/${pathSegments(this.path)}`, options);
+  }
+  async put(body, options = {}) {
+    if (options.retry && typeof body !== "function" && !isReplayable(body))
+      throw invalid("PUT retries require a replayable body or a body factory");
+    const headers = new Headers(options.headers);
+    if (options.contentType)
+      headers.set("content-type", options.contentType);
+    if (options.contentMD5)
+      headers.set("content-md5", options.contentMD5);
+    return this.call("PUT", `/__/files/${pathSegments(this.path)}`, { ...options, headers }, body, "write", options.retry === true);
+  }
+  async delete(options) {
+    await this.call("DELETE", `/__/files/${pathSegments(this.path)}`, options, undefined, "write");
+  }
+}
+
+class CanonicalFiles extends ClientCore {
+  listPage(options = {}, token) {
+    const query = new URLSearchParams;
+    if (options.prefix !== undefined)
+      query.set("prefix", validatePrefix(options.prefix));
+    query.set("limit", String(Math.min(1000, Math.max(1, options.limit ?? 1000))));
+    if (token)
+      query.set("continuation-token", token);
+    return this.request("GET", `/__/files?${query}`, { signal: options.signal }).then(async ({ response, attempt, lease }) => {
+      if (!lease.body)
+        throw new DcdnError("listing response has no body", { code: "STREAM_ERROR", attempt });
+      try {
+        const entries = JSON.parse(await new Response(lease.body).text());
+        if (!Array.isArray(entries) || !entries.every((entry) => typeof entry === "string"))
+          throw new TypeError("canonical listing must be an array of strings");
+        return { entries, continuationToken: response.headers.get("x-dcdn-continuation-token") ?? undefined };
+      } catch (cause) {
+        if (cause instanceof DcdnError)
+          throw cause;
+        throw new DcdnError("invalid canonical listing response", { code: "STREAM_ERROR", attempt, cause });
+      }
+    });
+  }
+  async* list(options = {}) {
+    let token;
+    do {
+      const page = await this.listPage(options, token);
+      yield* page.entries;
+      token = page.continuationToken;
+    } while (token);
+  }
+}
+
+class S3Object extends Resource {
+  bucketName;
+  objectKey;
+  constructor(options, bucketName, objectKey) {
+    super(options);
+    this.bucketName = bucketName;
+    this.objectKey = objectKey;
+  }
+  path() {
+    return `/s3/${pathSegment(this.bucketName)}/${pathSegments(this.objectKey)}`;
+  }
+  get(options) {
+    return this.call("GET", this.path(), options);
+  }
+  head(options) {
+    return this.call("HEAD", this.path(), options);
+  }
+  async put(body, options = {}) {
+    if (options.retry && typeof body !== "function" && !isReplayable(body))
+      throw invalid("PUT retries require a replayable body or a body factory");
+    const headers = new Headers(options.headers);
+    if (options.contentType)
+      headers.set("content-type", options.contentType);
+    if (options.contentMD5)
+      headers.set("content-md5", options.contentMD5);
+    const result = await this.call("PUT", this.path(), { ...options, headers }, body, "write", options.retry === true);
+    return { etag: result.headers.get("etag") ? normalizeEtag(result.headers.get("etag")) : undefined, response: result };
+  }
+  async delete(options) {
+    await this.call("DELETE", this.path(), options, undefined, "write");
+  }
+}
+
+class S3Bucket extends ClientCore {
+  name;
+  constructor(options, name) {
+    super(options);
+    this.name = name;
+  }
+  object(key) {
+    validateKey(key);
+    return new S3Object(this.options, this.name, key);
+  }
+  listPage(options = {}, token) {
+    const query = new URLSearchParams({ "list-type": "2" });
+    if (options.prefix)
+      query.set("prefix", options.prefix);
+    if (options.delimiter)
+      query.set("delimiter", options.delimiter);
+    query.set("max-keys", String(Math.min(1000, Math.max(1, options.maxKeys ?? 1000))));
+    if (token ?? options.continuationToken)
+      query.set("continuation-token", token ?? options.continuationToken);
+    if (options.startAfter)
+      query.set("start-after", options.startAfter);
+    if (options.encodingType)
+      query.set("encoding-type", options.encodingType);
+    return this.request("GET", `/s3/${pathSegment(this.name)}?${query}`, { signal: options.signal }).then(async ({ response, attempt, lease }) => {
+      if (!lease.body)
+        throw new DcdnError("listing response has no body", { code: "STREAM_ERROR", attempt });
+      return parseS3List(await new Response(lease.body).text(), attempt, options.encodingType === "url");
+    });
+  }
+  async* list(options = {}) {
+    let token;
+    do {
+      const page = await this.listPage(options, token);
+      yield* page.objects;
+      yield* page.commonPrefixes;
+      token = page.nextContinuationToken;
+    } while (token);
+  }
+}
+function DcdnClient(input) {
+  const base = new URL(input.baseUrl);
+  if (!/^https?:$/.test(base.protocol))
+    throw invalid("baseUrl must use http or https");
+  base.pathname = base.pathname.replace(/\/*$/, "/");
+  const options = { ...input, base, fetcher: input.fetch ?? globalThis.fetch, retry: input.retry === false ? { maxAttempts: 1 } : { ...input.retry } };
+  if (!options.fetcher)
+    throw invalid("fetch is unavailable");
+  return { file: (path) => {
+    validatePath(path);
+    return new CanonicalFile(options, path);
+  }, files: new CanonicalFiles(options), bucket: (name) => {
+    validateBucket(name);
+    return new S3Bucket(options, name);
+  } };
+}
+function validatePath(value) {
+  if (!value || value.startsWith("/") || value.includes("\\") || value.includes("\x00") || value.split("/").some((x) => !x || x === "." || x === ".."))
+    throw invalid("path must be a non-empty relative slash-separated path");
+  return value;
+}
+function validatePrefix(value) {
+  if (value === "")
+    return value;
+  if (value.startsWith("/") || value.includes("\\") || value.includes("\x00"))
+    throw invalid("prefix must be a relative slash-separated path");
+  const parts = value.split("/");
+  if (parts.at(-1) === "")
+    parts.pop();
+  if (!parts.length || parts.some((part) => !part || part === "." || part === ".."))
+    throw invalid("prefix must be a relative slash-separated path");
+  return value;
+}
+function validateKey(value) {
+  if (!value || value.startsWith("/") || value.includes("\\") || value.includes("\x00") || value.split("/").some((x) => x === "." || x === ".."))
+    throw invalid("key is invalid");
+  return value;
+}
+function validateBucket(value) {
+  if (!value || value.includes("/") || value.includes("\\") || value.includes("\x00") || value === "." || value === "..")
+    throw invalid("bucket is invalid");
+  return value;
+}
+function pathSegment(value) {
+  return encodeURIComponent(value);
+}
+function pathSegments(value) {
+  return value.split("/").map(pathSegment).join("/");
+}
+function positiveInt(value, name) {
+  if (!Number.isInteger(value) || value <= 0)
+    throw invalid(`${name} must be positive`);
+  return value;
+}
+function invalid(message) {
+  return new DcdnError(message, { code: "INVALID_INPUT" });
+}
+function isReplayable(body) {
+  return typeof body === "string" || body instanceof Blob || body instanceof ArrayBuffer || ArrayBuffer.isView(body);
+}
+function normalizeEtag(value) {
+  return value.trim().replace(/^"|"$/g, "");
+}
+function normalizeEtagInput(value) {
+  const trimmed = value.trim();
+  return trimmed === "*" ? "*" : `"${normalizeEtag(trimmed)}"`;
+}
+function metadata(response, range) {
+  const date = response.headers.get("last-modified");
+  return { status: response.status, headers: response.headers, size: Number(response.headers.get("content-length")) || undefined, contentType: response.headers.get("content-type") ?? undefined, etag: response.headers.get("etag") ? normalizeEtag(response.headers.get("etag")) : undefined, lastModified: date ? new Date(date) : undefined, range };
+}
+function bodyLease(response, controller, callerSignal, timer, requestAbort, attempt) {
+  const source = response.body;
+  let released = false;
+  let onAbort = () => {
+    return;
+  };
+  const release = () => {
+    if (released)
+      return;
+    released = true;
+    clearTimeout(timer);
+    callerSignal?.removeEventListener("abort", requestAbort);
+    controller.signal.removeEventListener("abort", onAbort);
+  };
+  if (!source) {
+    release();
+    return { body: null, release };
+  }
+  const reader = source.getReader();
+  let streamController;
+  onAbort = () => {
+    const error = callerSignal?.aborted ? new DcdnError("response body aborted", { code: "ABORTED", attempt, cause: callerSignal.reason }) : new DcdnError("response body timed out", { code: "TIMEOUT", attempt, cause: controller.signal.reason });
+    if (!released) {
+      release();
+      streamController?.error(error);
+    }
+    reader.cancel(error).catch(() => {
+      return;
+    });
+  };
+  controller.signal.addEventListener("abort", onAbort, { once: true });
+  const body = new ReadableStream({
+    start(c) {
+      streamController = c;
+    },
+    async pull(c) {
+      try {
+        const result = await reader.read();
+        if (result.done) {
+          release();
+          c.close();
+        } else
+          c.enqueue(result.value);
+      } catch (cause) {
+        release();
+        c.error(cause instanceof DcdnError ? cause : new DcdnError("response stream failed", { code: "STREAM_ERROR", attempt, cause }));
+      }
+    },
+    async cancel(reason) {
+      release();
+      await reader.cancel(reason);
+    }
+  });
+  if (callerSignal?.aborted || controller.signal.aborted)
+    onAbort();
+  return { body, release };
+}
+async function readBody(body, attempt, map) {
+  try {
+    if (!body)
+      return map(new Uint8Array);
+    return map(new Uint8Array(await new Response(body).arrayBuffer()));
+  } catch (cause) {
+    if (cause instanceof DcdnError)
+      throw cause;
+    throw new DcdnError("response stream failed", { code: "STREAM_ERROR", attempt, cause });
+  }
+}
+async function cancelResponseBody(response) {
+  await response.body?.cancel().catch(() => {
+    return;
+  });
+}
+async function waitRetry(headers, attempt, deadline, retry, signal) {
+  if (signal?.aborted)
+    throw new DcdnError("request aborted", { code: "ABORTED", attempt, cause: signal.reason });
+  const retryAfter = headers?.get("retry-after");
+  let delay = retryAfter ? parseRetryAfter(retryAfter) : undefined;
+  const base = retry.baseDelayMs ?? 100;
+  const max = retry.maxDelayMs ?? 1e4;
+  delay ??= Math.min(max, base * 2 ** (attempt - 1)) * (retry.random?.() ?? Math.random());
+  const remaining = deadline - Date.now();
+  if (remaining <= 0)
+    throw new DcdnError("request timed out", { code: "TIMEOUT", attempt });
+  const wait = Math.min(delay, remaining);
+  await new Promise((resolve, reject) => {
+    let settled = false;
+    const finish = (error) => {
+      if (settled)
+        return;
+      settled = true;
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+      error ? reject(error) : resolve();
+    };
+    const onAbort = () => finish(new DcdnError("request aborted", { code: "ABORTED", attempt, cause: signal?.reason }));
+    const timer = setTimeout(() => finish(wait < remaining ? undefined : new DcdnError("request timed out", { code: "TIMEOUT", attempt })), wait);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function parseRetryAfter(value) {
+  const seconds = Number(value);
+  if (Number.isFinite(seconds))
+    return Math.max(0, seconds * 1000);
+  const date = Date.parse(value);
+  return Number.isNaN(date) ? undefined : Math.max(0, date - Date.now());
+}
+async function responseError(response, attempt) {
+  let s3;
+  let message = `DCDN request failed with HTTP ${response.status}`;
+  if (response.headers.get("content-type")?.includes("xml")) {
+    const xml = await response.text().catch(() => "");
+    s3 = { code: tag(xml, "Code"), requestId: tag(xml, "RequestId"), hostId: tag(xml, "HostId") };
+    message = tag(xml, "Message") ?? s3.code ?? message;
+  }
+  return new DcdnError(message, { code: "HTTP_ERROR", status: response.status, retryable: retryStatuses.has(response.status), attempt, s3 });
+}
+function tag(xml, name) {
+  const match = xml.match(new RegExp(`<${name}(?:\\s[^>]*)?>([\\s\\S]*?)</${name}>`, "i"));
+  return match ? decodeXml(match[1]) : undefined;
+}
+function decodeXml(value) {
+  return value.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, "&").replace(/&#(\d+);/g, (_, n) => String.fromCodePoint(Number(n)));
+}
+function parseS3List(xml, attempt, encoded) {
+  try {
+    validateXml(xml);
+    const rootMatch = xml.match(/^\s*(?:<\?xml[^>]*>\s*)?<ListBucketResult(?:\s[^>]*)?>([\s\S]*)<\/ListBucketResult>\s*$/i);
+    if (!rootMatch)
+      throw new SyntaxError("invalid ListBucketResult XML");
+    const root = rootMatch[1];
+    const required = (name) => {
+      const value = directTag(root, name);
+      if (value === undefined)
+        throw new TypeError(`missing S3 field ${name}`);
+      return value;
+    };
+    const decode = (value) => {
+      if (!encoded)
+        return value;
+      try {
+        return decodeURIComponent(value);
+      } catch (cause) {
+        throw new URIError(`invalid URL encoding in S3 listing: ${value}`, { cause });
+      }
+    };
+    const bucket = required("Name");
+    const prefix = decode(required("Prefix"));
+    const keyCount = Number(required("KeyCount"));
+    const maxKeys = Number(required("MaxKeys"));
+    const truncatedValue = required("IsTruncated");
+    if (!bucket || !Number.isInteger(keyCount) || keyCount < 0 || !Number.isInteger(maxKeys) || maxKeys < 0 || !/^(true|false)$/.test(truncatedValue))
+      throw new TypeError("invalid S3 pagination fields");
+    const isTruncated = truncatedValue === "true";
+    const next = directTag(root, "NextContinuationToken");
+    if (isTruncated && next === undefined)
+      throw new TypeError("missing S3 field NextContinuationToken");
+    const objects = [...root.matchAll(/<Contents(?:\s[^>]*)?>([\s\S]*?)<\/Contents>/gi)].map((match) => {
+      const content = match[1];
+      const field = (name) => {
+        const value = directTag(content, name);
+        if (value === undefined)
+          throw new TypeError(`missing S3 object field ${name}`);
+        return value;
+      };
+      const size = Number(field("Size"));
+      if (!Number.isInteger(size) || size < 0)
+        throw new TypeError("invalid S3 object size");
+      const lastModified = field("LastModified");
+      const date = new Date(lastModified);
+      if (Number.isNaN(date.valueOf()))
+        throw new TypeError("invalid S3 object date");
+      const etag = directTag(content, "ETag");
+      return { key: decode(field("Key")), size, etag: etag === undefined ? undefined : normalizeEtag(etag), lastModified: date };
+    });
+    const commonPrefixes = [...root.matchAll(/<CommonPrefixes(?:\s[^>]*)?>([\s\S]*?)<\/CommonPrefixes>/gi)].map((match) => {
+      const value = directTag(match[1], "Prefix");
+      if (value === undefined)
+        throw new TypeError("missing S3 common prefix");
+      return decode(value);
+    });
+    return { bucket, prefix, keyCount, maxKeys, isTruncated, nextContinuationToken: next === undefined ? undefined : decode(next), objects, commonPrefixes };
+  } catch (cause) {
+    if (cause instanceof DcdnError)
+      throw cause;
+    throw new DcdnError("invalid S3 XML response", { code: "STREAM_ERROR", attempt, cause });
+  }
+}
+function validateXml(xml) {
+  const stack = [];
+  for (const match of xml.matchAll(/<!--[\s\S]*?-->|<\?[^>]*>|<![^>]*>|<\/?([A-Za-z_][\w:.-]*)(?:\s[^<>]*?)?\/?\s*>/g)) {
+    const token = match[0];
+    if (token.startsWith("<!--") || token.startsWith("<?") || token.startsWith("<!"))
+      continue;
+    const name = match[1];
+    if (token.startsWith("</")) {
+      if (stack.pop() !== name)
+        throw new SyntaxError("malformed XML");
+    } else if (!/\/\s*>$/.test(token))
+      stack.push(name);
+  }
+  if (stack.length || /<[^>]*$/.test(xml))
+    throw new SyntaxError("malformed XML");
+}
+function directTag(xml, name) {
+  const tags = [...xml.matchAll(/<\/?([A-Za-z_][\w:.-]*)(?:\s[^<>]*?)?\/?\s*>/g)];
+  const stack = [];
+  let valueStart = 0;
+  for (const match of tags) {
+    const token = match[0];
+    if (token.startsWith("</")) {
+      if (stack.length === 1 && stack[0] === name)
+        return decodeXml(xml.slice(valueStart, match.index));
+      stack.pop();
+    } else if (!/\/\s*>$/.test(token)) {
+      if (stack.length === 0 && match[1] === name)
+        valueStart = (match.index ?? 0) + token.length;
+      stack.push(match[1]);
+    }
+  }
+  return;
+}
+export {
+  bytesRange,
+  byteRange,
+  DcdnError,
+  DcdnClient
+};

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@dmgnr/dcdn",
+  "version": "0.1.0",
+  "description": "Conservative TypeScript client for DCDN canonical files and S3-compatible objects",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+  ".": {
+  "types": "./dist/index.d.ts",
+  "import": "./dist/index.js"
+}
+},
+"files": ["dist", "README.md"],
+"scripts": {
+"build": "bun run clean && bun build src/index.ts --outdir dist --target bun && tsc -p tsconfig.build.json",
+"clean": "rm -rf dist",
+"typecheck": "tsc --noEmit",
+"test": "bun test"
+},
+"engines": {
+"node": ">=18",
+"bun": ">=1.0"
+},
+"devDependencies": {
+"@types/bun": "latest",
+"typescript": "^5.7.0"
+}
+}