@classic-homes/files-core 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,29 @@
-# Temporary Holding Version
+# @classic-homes/files-core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Framework-agnostic network-drive browsing for Classic Theme:
+
+- `FilesSource`: the interface every file browser binding reads from
+- `createChapiFilesSource()`: CHAPI's `/v2/files` API (the on-prem SMB gateway), read-only
+- `createMemoryFilesSource()`: an in-memory drive for demos and tests
+- `FilesError` with typed codes, `describeFilesError()` for user-facing copy
+- Path, sort, filter, size/date formatting and file-kind helpers
+
+No runtime dependencies. Svelte components: [`@classic-homes/files-svelte`](../files-svelte).
+
+```ts
+import { createChapiFilesSource } from '@classic-homes/files-core';
+import { getAccessToken, refreshSession } from '@classic-homes/auth/core';
+
+const files = createChapiFilesSource({
+  baseUrl: 'https://api.classichomes.com',
+  getAccessToken,
+  onUnauthorized: async () => (await refreshSession()) === 'refreshed',
+});
+
+const roots = await files.listRoots();
+const page = await files.list(roots[0].id, '', { limit: 200 });
+```
+
+`canWrite` is true only when the caller's access is `write` **and** the service is not read-only; there are no write endpoints yet, so the adapter has no write methods.
+
+Docs: `/docs/utilities/files-source` in the Svelte demo app.

package/dist/index.d.ts

@@ -0,0 +1,335 @@
+/**
+ * The data model shared by every files source (CHAPI, in-memory, custom) and
+ * every framework binding. Paths are always root-relative, `/` separated, with
+ * `''` for the root itself.
+ */
+/** `link` = symlink / junction / shortcut: shown in listings, never opened. */
+type FileEntryType = 'file' | 'dir' | 'link';
+interface FileEntry {
+    name: string;
+    /** Root-relative, `/` separated; `''` is the root. Treat the server's value as the truth. */
+    path: string;
+    type: FileEntryType;
+    /** Bytes; 0 for directories. */
+    size: number;
+    /** ISO 8601 timestamp. */
+    modified: string;
+    /** Already quoted, e.g. `"\"18a8…-10366\""`. Kept for `If-Match` on future writes. */
+    etag?: string;
+    hidden: boolean;
+}
+interface FileRoot {
+    id: string;
+    label: string;
+    description?: string | null;
+    /** True only when the caller may write AND the service accepts writes. */
+    canWrite: boolean;
+}
+interface FileListPage {
+    entries: FileEntry[];
+    /** Entries in the whole folder, when the source knows. */
+    total?: number;
+    /** Pass back as `cursor` for the next page; `null`/absent when there are no more. */
+    nextCursor?: string | null;
+}
+interface ListOptions {
+    cursor?: string;
+    /** Page size, 1–1000. The CHAPI default is 200. */
+    limit?: number;
+    includeHidden?: boolean;
+    signal?: AbortSignal;
+}
+interface ReadOptions {
+    /** Ask for `Content-Disposition: attachment`. */
+    download?: boolean;
+    signal?: AbortSignal;
+}
+interface SearchOptions extends ListOptions {
+    /** Folder to search under; `''` (the default) searches the whole root. */
+    path?: string;
+}
+/** Options for a future upload. */
+interface UploadOptions {
+    /** Overwrite only when the current entry still has this etag (`If-Match`). */
+    ifMatch?: string;
+    signal?: AbortSignal;
+}
+/** Options for future move/remove calls. */
+interface WriteOptions {
+    ifMatch?: string;
+    signal?: AbortSignal;
+}
+/**
+ * Where a file browser gets its data. Components never call `fetch`
+ * themselves: pass `createChapiFilesSource()` in apps and
+ * `createMemoryFilesSource()` in demos and tests, or write your own.
+ */
+interface FilesSource {
+    /** Roots the caller may read. */
+    listRoots(signal?: AbortSignal): Promise<FileRoot[]>;
+    /** One page of a folder: directories first, then names, case-insensitively. */
+    list(rootId: string, path: string, opts?: ListOptions): Promise<FileListPage>;
+    info(rootId: string, path: string, signal?: AbortSignal): Promise<FileEntry>;
+    /** Bytes for preview or download. Must send auth, so it returns a Blob, not a URL. */
+    read(rootId: string, path: string, opts?: ReadOptions): Promise<Blob>;
+    /**
+     * Server-side name search. Not offered by CHAPI yet; when a source has it,
+     * FileBrowser's filter box searches the whole root instead of the loaded page.
+     */
+    search?(rootId: string, query: string, opts?: SearchOptions): Promise<FileListPage>;
+    upload?(rootId: string, path: string, file: Blob, opts?: UploadOptions): Promise<FileEntry>;
+    mkdir?(rootId: string, path: string, signal?: AbortSignal): Promise<FileEntry>;
+    move?(rootId: string, from: string, to: string, opts?: WriteOptions): Promise<FileEntry>;
+    remove?(rootId: string, path: string, opts?: WriteOptions): Promise<void>;
+}
+/** Which write actions a root offers through a source. All false while a root is read-only. */
+interface WriteCapabilities {
+    upload: boolean;
+    mkdir: boolean;
+    move: boolean;
+    remove: boolean;
+    /** Any of the above. */
+    any: boolean;
+}
+declare function writeCapabilities(source: FilesSource, root: FileRoot | undefined | null): WriteCapabilities;
+
+/**
+ * Typed errors for files sources, so a UI can render the right state without
+ * parsing messages. CHAPI puts the gateway's code in `error.details.reason`.
+ */
+type FilesErrorCode = 'invalid_path' | 'not_a_directory' | 'is_directory' | 'invalid_cursor' | 'unauthorized' | 'link_not_followed' | 'access_denied' | 'not_found' | 'locked' | 'unavailable' | 'timeout' | 'file_server_error' | 'network' | 'unknown';
+declare const BAD_REQUEST_REASONS: readonly ["invalid_path", "not_a_directory", "is_directory", "invalid_cursor"];
+interface FilesErrorInit {
+    status?: number;
+    /** Seconds to wait before retrying (from `Retry-After`). */
+    retryAfter?: number;
+    /** The raw reason / code the server sent, when it differs from `code`. */
+    reason?: string;
+    cause?: unknown;
+}
+declare class FilesError extends Error {
+    readonly name = "FilesError";
+    readonly code: FilesErrorCode;
+    /** HTTP status, 0 when the request never got a response. */
+    readonly status: number;
+    readonly retryAfter?: number;
+    readonly reason?: string;
+    constructor(code: FilesErrorCode, message: string, init?: FilesErrorInit);
+}
+declare function isFilesError(value: unknown): value is FilesError;
+/** A cancelled request (our own `AbortController`), which a UI should ignore. */
+declare function isAbortError(value: unknown): boolean;
+/** Map an HTTP status plus the server's reason/code to a {@link FilesErrorCode}. */
+declare function filesErrorCode(status: number, reason?: string): FilesErrorCode;
+/** What the UI should offer next to an error. */
+type FilesErrorAction = 'retry' | 'root' | 'none';
+interface FilesErrorDescription {
+    title: string;
+    description: string;
+    action: FilesErrorAction;
+}
+/**
+ * User-facing copy for an error. Staff never see server names, status codes
+ * or the gateway's raw messages.
+ */
+declare function describeFilesError(error: unknown): FilesErrorDescription;
+/** Seconds from a `Retry-After` header (delta-seconds or HTTP date). */
+declare function parseRetryAfter(header: string | null | undefined, now?: number): number | undefined;
+
+/**
+ * Normalise a root-relative path: backslashes become `/`, empty and `.`
+ * segments are dropped. Throws `FilesError('invalid_path')` for `..`.
+ */
+declare function normalizePath(path: string | null | undefined): string;
+/** Join path parts: `joinPath('Lots', '14/Plans')` → `'Lots/14/Plans'`. */
+declare function joinPath(...parts: (string | null | undefined)[]): string;
+/** Parent folder; the root's parent is the root. */
+declare function parentPath(path: string): string;
+/** Last segment (`''` for the root). */
+declare function baseName(path: string): string;
+interface PathSegment {
+    name: string;
+    /** Path of this folder, from the root. */
+    path: string;
+}
+/** Each folder from the root down: `'A/B'` → `[{ name: 'A', path: 'A' }, { name: 'B', path: 'A/B' }]`. */
+declare function pathSegments(path: string): PathSegment[];
+/** True when `path` is `ancestor` or inside it. */
+declare function isWithin(path: string, ancestor: string): boolean;
+/** Root label plus path, for pasting into chat (never a UNC path). */
+declare function displayPath(rootLabel: string, path: string): string;
+
+/** Locale-aware display helpers for sizes and dates. */
+interface FormatBytesOptions {
+    locale?: string | string[];
+    /** Maximum fraction digits for KB and up. Default 1. */
+    decimals?: number;
+}
+/**
+ * Human-readable size in binary units, labelled as Windows Explorer does:
+ * `1536` → `"1.5 KB"`. Negative or non-finite input returns `''`.
+ */
+declare function formatBytes(bytes: number, options?: FormatBytesOptions): string;
+/** Absolute date and time in the viewer's locale and time zone, e.g. for a tooltip. */
+declare function formatDateTime(value: string | number | Date, locale?: string | string[], options?: Intl.DateTimeFormatOptions): string;
+interface FormatRelativeOptions {
+    locale?: string | string[];
+    /** Reference time. Default now. */
+    now?: number | Date;
+}
+/**
+ * Relative time, e.g. `"3 days ago"`, `"yesterday"`, `"just now"`. Older
+ * than a year shows the date instead, which reads better in a file list.
+ */
+declare function formatRelativeTime(value: string | number | Date, options?: FormatRelativeOptions): string;
+
+/** File kinds by extension, for icons and preview routing. */
+
+type FileKind = 'folder' | 'link' | 'pdf' | 'word' | 'excel' | 'csv' | 'cad' | 'image' | 'archive' | 'text' | 'generic';
+/** Lower-cased extension without the dot (`''` when there is none). */
+declare function fileExtension(name: string): string;
+/** Kind of a file from its name alone. */
+declare function kindForName(name: string): FileKind;
+/** Kind of an entry: folders and links first, then the name's extension. */
+declare function kindForEntry(entry: Pick<FileEntry, 'name' | 'type'>): FileKind;
+/** Short label for a kind, e.g. for a details card. */
+declare const KIND_LABELS: Record<FileKind, string>;
+/** Document viewer formats (matches `@classic-homes/viewer-core` RenderableKind). */
+type DocumentPreviewKind = 'pdf' | 'docx' | 'xlsx' | 'csv' | 'dxf' | 'dwg';
+/**
+ * Never rendered inline, whatever the content: the gateway serves these as an
+ * attachment under a sandbox CSP.
+ */
+declare const NEVER_INLINE_EXTENSIONS: readonly string[];
+type PreviewRoute = {
+    kind: 'document';
+    format: DocumentPreviewKind;
+} | {
+    kind: 'image';
+} | {
+    kind: 'none';
+};
+/**
+ * How a file can be previewed. Pass the formats the app registered viewers
+ * for; anything else (and every never-inline type) gets `{ kind: 'none' }`,
+ * i.e. a details card with a Download button.
+ */
+declare function previewRoute(entry: Pick<FileEntry, 'name' | 'type'>, documentFormats?: readonly string[]): PreviewRoute;
+
+/** Client-side sort and filter over the entries already loaded. */
+
+type FileSortKey = 'name' | 'modified' | 'size' | 'type';
+type SortDirection = 'asc' | 'desc';
+interface FileSort {
+    key: FileSortKey;
+    direction: SortDirection;
+}
+/**
+ * The server's order: directories first, then names case-insensitively.
+ * Useful for sources that build listings themselves.
+ */
+declare function compareEntries(a: FileEntry, b: FileEntry): number;
+/**
+ * Sort a copy of `entries` by a column. Folders stay above files in either
+ * direction, as in Explorer. Ties fall back to the name.
+ */
+declare function sortEntries(entries: readonly FileEntry[], sort: FileSort): FileEntry[];
+/** Entries whose name contains `query` (case- and accent-insensitive). */
+declare function filterEntries(entries: readonly FileEntry[], query: string): FileEntry[];
+
+/** Save a Blob as a file. Downloads need the bearer header, so a plain `<a href>` to the API won't do. */
+declare function saveBlob(blob: Blob, filename: string): void;
+
+type MaybePromise<T> = T | Promise<T>;
+interface ChapiFilesSourceOptions {
+    /** CHAPI origin, e.g. `https://api.classichomes.com`. A trailing `/v1` or `/v2` is ignored. */
+    baseUrl: string;
+    /** The app's CHAPI bearer token, sent on every request. */
+    getAccessToken?: () => MaybePromise<string | null | undefined>;
+    /** Extra headers per request (e.g. `X-Session-Token`). */
+    getHeaders?: () => MaybePromise<Record<string, string> | undefined>;
+    /**
+     * Called on a 401. Return `true` once the session is refreshed to retry the
+     * request once with the new token, e.g.
+     * `async () => (await refreshSession()) === 'refreshed'` with `@classic-homes/auth/core`.
+     */
+    onUnauthorized?: () => MaybePromise<boolean>;
+    /** Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+    /** Time to wait for response headers. Default 30 s. File bodies may then take as long as they need. */
+    timeoutMs?: number;
+}
+/** Shape of a root in `GET /v2/files/roots`. */
+interface ChapiRoot {
+    id: string;
+    label?: string;
+    description?: string | null;
+    access?: 'read' | 'write';
+    active?: boolean;
+    service?: {
+        configured?: boolean;
+        readOnly?: boolean;
+    };
+}
+declare const DEFAULT_TIMEOUT_MS = 30000;
+declare const DEFAULT_PAGE_SIZE = 200;
+declare const MAX_PAGE_SIZE = 1000;
+/** `https://api.example.com/v1/` → `https://api.example.com`. */
+declare function chapiOrigin(baseUrl: string): string;
+/**
+ * `canWrite` needs both: the caller's access is `write` AND the service is
+ * not read-only. Admins see `access: 'write'` on every root, so `access`
+ * alone is never enough.
+ */
+declare function rootFromChapi(root: ChapiRoot): FileRoot;
+/** Defensive copy of a server entry (unknown types are treated as files). */
+declare function entryFromChapi(raw: Partial<FileEntry>): FileEntry;
+declare function createChapiFilesSource(options: ChapiFilesSourceOptions): FilesSource;
+
+/**
+ * An in-memory FilesSource for demos, tests and storybook-style pages. It
+ * behaves like CHAPI: paging with opaque cursors, hidden files, links that
+ * are listed but never followed, and the same typed errors.
+ */
+
+type MemoryContent = Blob | string | (() => Blob | Promise<Blob>);
+interface MemoryFile {
+    /** Root-relative path. Parent folders are created implicitly. */
+    path: string;
+    /** Default `'file'`. */
+    type?: FileEntryType;
+    /** Defaults to the content's size, or 0. */
+    size?: number;
+    modified?: string;
+    hidden?: boolean;
+    etag?: string;
+    content?: MemoryContent;
+}
+interface MemoryRoot extends FileRoot {
+    files: MemoryFile[];
+}
+type MemoryOperation = 'listRoots' | 'list' | 'info' | 'read' | 'search';
+interface MemoryRequest {
+    op: MemoryOperation;
+    rootId?: string;
+    path?: string;
+}
+interface MemoryFilesSourceOptions {
+    roots: MemoryRoot[];
+    /** Simulated latency per call, in ms. Default 0. */
+    latency?: number;
+    /** Page size when `list()` is called without a limit. Default 200. */
+    defaultLimit?: number;
+    /**
+     * Called before every request; return (or throw) a FilesError to fail it.
+     * The demo uses this for its error toggles.
+     */
+    intercept?: (request: MemoryRequest) => FilesError | void | undefined;
+    /** Offer `search()` (whole-root name search). Default false, like CHAPI today. */
+    search?: boolean;
+    /** Default modified time for entries without one. */
+    now?: string;
+}
+declare function createMemoryFilesSource(options: MemoryFilesSourceOptions): FilesSource;
+
+export { BAD_REQUEST_REASONS, type ChapiFilesSourceOptions, DEFAULT_PAGE_SIZE, DEFAULT_TIMEOUT_MS, type DocumentPreviewKind, type FileEntry, type FileEntryType, type FileKind, type FileListPage, type FileRoot, type FileSort, type FileSortKey, FilesError, type FilesErrorAction, type FilesErrorCode, type FilesErrorDescription, type FilesErrorInit, type FilesSource, type FormatBytesOptions, type FormatRelativeOptions, KIND_LABELS, type ListOptions, MAX_PAGE_SIZE, type MemoryContent, type MemoryFile, type MemoryFilesSourceOptions, type MemoryOperation, type MemoryRequest, type MemoryRoot, NEVER_INLINE_EXTENSIONS, type PathSegment, type PreviewRoute, type ReadOptions, type SearchOptions, type SortDirection, type UploadOptions, type WriteCapabilities, type WriteOptions, baseName, chapiOrigin, compareEntries, createChapiFilesSource, createMemoryFilesSource, describeFilesError, displayPath, entryFromChapi, fileExtension, filesErrorCode, filterEntries, formatBytes, formatDateTime, formatRelativeTime, isAbortError, isFilesError, isWithin, joinPath, kindForEntry, kindForName, normalizePath, parentPath, parseRetryAfter, pathSegments, previewRoute, rootFromChapi, saveBlob, sortEntries, writeCapabilities };

package/dist/index.js

@@ -0,0 +1,741 @@
+// src/types.ts
+function writeCapabilities(source, root) {
+  const allowed = !!root?.canWrite;
+  const caps = {
+    upload: allowed && typeof source.upload === "function",
+    mkdir: allowed && typeof source.mkdir === "function",
+    move: allowed && typeof source.move === "function",
+    remove: allowed && typeof source.remove === "function"
+  };
+  return { ...caps, any: caps.upload || caps.mkdir || caps.move || caps.remove };
+}
+
+// src/errors.ts
+var BAD_REQUEST_REASONS = [
+  "invalid_path",
+  "not_a_directory",
+  "is_directory",
+  "invalid_cursor"
+];
+var FilesError = class extends Error {
+  constructor(code, message, init = {}) {
+    super(message, init.cause === void 0 ? void 0 : { cause: init.cause });
+    this.name = "FilesError";
+    this.code = code;
+    this.status = init.status ?? 0;
+    this.retryAfter = init.retryAfter;
+    this.reason = init.reason;
+  }
+};
+function isFilesError(value) {
+  return value instanceof FilesError || typeof value === "object" && value !== null && value.name === "FilesError" && typeof value.code === "string";
+}
+function isAbortError(value) {
+  return typeof value === "object" && value !== null && value.name === "AbortError";
+}
+function filesErrorCode(status, reason) {
+  const r = reason?.toLowerCase();
+  switch (status) {
+    case 400:
+      return BAD_REQUEST_REASONS.includes(r ?? "") ? r : "invalid_path";
+    case 401:
+      return "unauthorized";
+    case 403:
+      return r === "link_not_followed" ? "link_not_followed" : "access_denied";
+    case 404:
+      return "not_found";
+    case 423:
+      return "locked";
+    case 503:
+      return "unavailable";
+    case 504:
+      return "timeout";
+    case 502:
+      return "file_server_error";
+    default:
+      return status >= 500 ? "file_server_error" : "unknown";
+  }
+}
+function describeFilesError(error) {
+  const code = isFilesError(error) ? error.code : "unknown";
+  switch (code) {
+    case "invalid_path":
+    case "not_a_directory":
+    case "is_directory":
+    case "invalid_cursor":
+      return {
+        title: "This location can't be opened",
+        description: "The address may be mistyped or out of date.",
+        action: "root"
+      };
+    case "unauthorized":
+      return {
+        title: "Your session has ended",
+        description: "Sign in again to keep browsing.",
+        action: "none"
+      };
+    case "link_not_followed":
+      return {
+        title: "This shortcut can't be opened here",
+        description: "This is a shortcut to another location and can't be opened here.",
+        action: "none"
+      };
+    case "access_denied":
+      return {
+        title: "You don't have access to this folder",
+        description: "Ask the folder owner or IT if you need it.",
+        action: "none"
+      };
+    case "not_found":
+      return {
+        title: "This folder no longer exists",
+        description: "It may have been moved, renamed or deleted.",
+        action: "root"
+      };
+    case "locked":
+      return {
+        title: "This file is in use",
+        description: "Someone has this file open (often in Office). Try again shortly.",
+        action: "retry"
+      };
+    case "unavailable":
+      return {
+        title: "The network drive is unavailable",
+        description: "It may be busy or down for maintenance.",
+        action: "retry"
+      };
+    case "timeout":
+    case "file_server_error":
+    case "network":
+      return {
+        title: "Couldn't reach the file server",
+        description: "Check your connection and try again.",
+        action: "retry"
+      };
+    default:
+      return {
+        title: "Something went wrong",
+        description: "Try again in a moment.",
+        action: "retry"
+      };
+  }
+}
+function parseRetryAfter(header, now = Date.now()) {
+  if (!header) return void 0;
+  const trimmed = header.trim();
+  if (/^\d+$/.test(trimmed)) return Number(trimmed);
+  const date = Date.parse(trimmed);
+  if (Number.isNaN(date)) return void 0;
+  return Math.max(0, Math.ceil((date - now) / 1e3));
+}
+
+// src/path.ts
+function normalizePath(path) {
+  if (!path) return "";
+  const segments = [];
+  for (const segment of path.replace(/\\/g, "/").split("/")) {
+    if (segment === "" || segment === ".") continue;
+    if (segment === "..") {
+      throw new FilesError("invalid_path", 'Paths may not contain "..".', { status: 400 });
+    }
+    segments.push(segment);
+  }
+  return segments.join("/");
+}
+function joinPath(...parts) {
+  return normalizePath(parts.filter((p) => p).join("/"));
+}
+function parentPath(path) {
+  const normal = normalizePath(path);
+  const slash = normal.lastIndexOf("/");
+  return slash < 0 ? "" : normal.slice(0, slash);
+}
+function baseName(path) {
+  const normal = normalizePath(path);
+  return normal.slice(normal.lastIndexOf("/") + 1);
+}
+function pathSegments(path) {
+  const normal = normalizePath(path);
+  if (!normal) return [];
+  const names = normal.split("/");
+  return names.map((name, i) => ({ name, path: names.slice(0, i + 1).join("/") }));
+}
+function isWithin(path, ancestor) {
+  const p = normalizePath(path);
+  const a = normalizePath(ancestor);
+  return a === "" || p === a || p.startsWith(`${a}/`);
+}
+function displayPath(rootLabel, path) {
+  const normal = normalizePath(path);
+  return normal ? `${rootLabel} / ${normal.split("/").join(" / ")}` : rootLabel;
+}
+
+// src/format.ts
+var UNITS = ["B", "KB", "MB", "GB", "TB", "PB"];
+function formatBytes(bytes, options = {}) {
+  if (!Number.isFinite(bytes) || bytes < 0) return "";
+  const { locale, decimals = 1 } = options;
+  let value = bytes;
+  let unit = 0;
+  while (value >= 1024 && unit < UNITS.length - 1) {
+    value /= 1024;
+    unit++;
+  }
+  const factor = 10 ** decimals;
+  if (unit > 0 && Math.round(value * factor) / factor >= 1024 && unit < UNITS.length - 1) {
+    value /= 1024;
+    unit++;
+  }
+  const number = new Intl.NumberFormat(locale, {
+    maximumFractionDigits: unit === 0 ? 0 : decimals
+  }).format(value);
+  return `${number} ${UNITS[unit]}`;
+}
+function toDate(value) {
+  const date = value instanceof Date ? value : new Date(value);
+  return Number.isNaN(date.getTime()) ? void 0 : date;
+}
+function formatDateTime(value, locale, options = { dateStyle: "medium", timeStyle: "short" }) {
+  const date = toDate(value);
+  return date ? new Intl.DateTimeFormat(locale, options).format(date) : "";
+}
+var RELATIVE_STEPS = [
+  ["second", 60],
+  ["minute", 60],
+  ["hour", 24],
+  ["day", 7],
+  ["week", 4.348],
+  ["month", 12],
+  ["year", Infinity]
+];
+function formatRelativeTime(value, options = {}) {
+  const date = toDate(value);
+  if (!date) return "";
+  const now = options.now instanceof Date ? options.now.getTime() : options.now ?? Date.now();
+  let delta = (date.getTime() - now) / 1e3;
+  if (Math.abs(delta) < 45) {
+    return new Intl.RelativeTimeFormat(options.locale, { numeric: "auto" }).format(0, "second");
+  }
+  if (Math.abs(delta) >= 365 * 24 * 3600) {
+    return formatDateTime(date, options.locale, { dateStyle: "medium" });
+  }
+  const rtf = new Intl.RelativeTimeFormat(options.locale, { numeric: "auto" });
+  for (const [unit, size] of RELATIVE_STEPS) {
+    if (Math.abs(delta) < size) return rtf.format(Math.round(delta), unit);
+    delta /= size;
+  }
+  return formatDateTime(date, options.locale, { dateStyle: "medium" });
+}
+
+// src/kind.ts
+var EXTENSIONS = {
+  pdf: ["pdf"],
+  word: ["doc", "docx", "docm", "dot", "dotx", "rtf", "odt"],
+  excel: ["xls", "xlsx", "xlsm", "xlsb", "xlt", "xltx", "ods"],
+  csv: ["csv", "tsv"],
+  cad: ["dwg", "dxf", "dwf", "dwfx", "dgn", "rvt", "skp", "ifc"],
+  image: ["png", "jpg", "jpeg", "gif", "webp", "bmp", "avif", "tif", "tiff", "heic", "svg"],
+  archive: ["zip", "7z", "rar", "tar", "gz", "tgz", "bz2", "xz"],
+  text: ["txt", "md", "log", "json", "xml", "html", "htm", "js", "ts", "css", "ini", "yml", "yaml"]
+};
+var BY_EXTENSION = new Map(
+  Object.entries(EXTENSIONS).flatMap(([kind, exts]) => exts.map((e) => [e, kind]))
+);
+function fileExtension(name) {
+  const base = name.slice(name.lastIndexOf("/") + 1);
+  const dot = base.lastIndexOf(".");
+  return dot > 0 ? base.slice(dot + 1).toLowerCase() : "";
+}
+function kindForName(name) {
+  return BY_EXTENSION.get(fileExtension(name)) ?? "generic";
+}
+function kindForEntry(entry) {
+  if (entry.type === "dir") return "folder";
+  if (entry.type === "link") return "link";
+  return kindForName(entry.name);
+}
+var KIND_LABELS = {
+  folder: "Folder",
+  link: "Shortcut",
+  pdf: "PDF document",
+  word: "Word document",
+  excel: "Excel workbook",
+  csv: "CSV file",
+  cad: "CAD drawing",
+  image: "Image",
+  archive: "Archive",
+  text: "Text file",
+  generic: "File"
+};
+var DOCUMENT_PREVIEW = {
+  pdf: "pdf",
+  docx: "docx",
+  docm: "docx",
+  xlsx: "xlsx",
+  xlsm: "xlsx",
+  csv: "csv",
+  dxf: "dxf",
+  dwg: "dwg"
+};
+var PREVIEW_IMAGES = /* @__PURE__ */ new Set(["png", "jpg", "jpeg", "gif", "webp", "bmp", "avif"]);
+var NEVER_INLINE_EXTENSIONS = [
+  "html",
+  "htm",
+  "xhtml",
+  "svg",
+  "svgz",
+  "xml",
+  "xsl",
+  "js",
+  "mjs"
+];
+function previewRoute(entry, documentFormats = []) {
+  if (entry.type !== "file") return { kind: "none" };
+  const ext = fileExtension(entry.name);
+  if (NEVER_INLINE_EXTENSIONS.includes(ext)) return { kind: "none" };
+  if (PREVIEW_IMAGES.has(ext)) return { kind: "image" };
+  const format = DOCUMENT_PREVIEW[ext];
+  if (format && documentFormats.includes(format)) return { kind: "document", format };
+  return { kind: "none" };
+}
+
+// src/sort.ts
+var collator = new Intl.Collator(void 0, { sensitivity: "base", numeric: true });
+function groupOf(entry) {
+  return entry.type === "dir" ? 0 : entry.type === "link" ? 1 : 2;
+}
+function compareEntries(a, b) {
+  return (a.type === "dir" ? 0 : 1) - (b.type === "dir" ? 0 : 1) || a.name.toLowerCase().localeCompare(b.name.toLowerCase(), "en") || (a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+}
+function sortEntries(entries, sort) {
+  const dir = sort.direction === "desc" ? -1 : 1;
+  const byName = (a, b) => collator.compare(a.name, b.name);
+  const byKey = (a, b) => {
+    switch (sort.key) {
+      case "modified":
+        return Date.parse(a.modified) - Date.parse(b.modified) || 0;
+      case "size":
+        return a.size - b.size;
+      case "type":
+        return collator.compare(extension(a), extension(b));
+      default:
+        return byName(a, b);
+    }
+  };
+  return [...entries].sort(
+    (a, b) => groupOf(a) - groupOf(b) || dir * byKey(a, b) || dir * byName(a, b)
+  );
+}
+function extension(entry) {
+  const dot = entry.name.lastIndexOf(".");
+  return entry.type === "file" && dot > 0 ? entry.name.slice(dot + 1) : "";
+}
+function filterEntries(entries, query) {
+  const needle = fold(query.trim());
+  if (!needle) return [...entries];
+  return entries.filter((e) => fold(e.name).includes(needle));
+}
+function fold(text) {
+  return text.normalize("NFD").replace(/[̀-ͯ]/g, "").toLowerCase();
+}
+
+// src/download.ts
+function saveBlob(blob, filename) {
+  if (typeof document === "undefined") return;
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = filename;
+  a.rel = "noopener";
+  a.style.display = "none";
+  document.body.appendChild(a);
+  a.click();
+  a.remove();
+  setTimeout(() => URL.revokeObjectURL(url), 1e3);
+}
+
+// src/chapi.ts
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_PAGE_SIZE = 200;
+var MAX_PAGE_SIZE = 1e3;
+function chapiOrigin(baseUrl) {
+  return baseUrl.trim().replace(/\/+$/, "").replace(/\/v[12]$/, "").replace(/\/+$/, "");
+}
+function rootFromChapi(root) {
+  return {
+    id: root.id,
+    label: root.label || root.id,
+    description: root.description ?? null,
+    canWrite: root.access === "write" && root.service?.readOnly === false
+  };
+}
+var ENTRY_TYPES = ["file", "dir", "link"];
+function entryFromChapi(raw) {
+  const type = ENTRY_TYPES.includes(raw.type) ? raw.type : "file";
+  const entry = {
+    name: String(raw.name ?? ""),
+    path: String(raw.path ?? raw.name ?? ""),
+    type,
+    size: type === "dir" ? 0 : Number(raw.size) || 0,
+    modified: String(raw.modified ?? ""),
+    hidden: raw.hidden === true
+  };
+  if (raw.etag) entry.etag = raw.etag;
+  return entry;
+}
+var MESSAGES = {
+  unauthorized: "Your session has ended. Sign in again.",
+  network: "Could not reach the file server.",
+  timeout: "The file server did not respond in time."
+};
+async function errorFromResponse(res) {
+  let body = null;
+  try {
+    body = await res.json();
+  } catch {
+    body = null;
+  }
+  const reason = body?.error?.details?.reason ?? body?.error?.code;
+  const code = filesErrorCode(res.status, reason);
+  return new FilesError(
+    code,
+    body?.error?.message || MESSAGES[code] || `Request failed (${res.status})`,
+    {
+      status: res.status,
+      reason,
+      retryAfter: parseRetryAfter(res.headers.get("retry-after"))
+    }
+  );
+}
+function createChapiFilesSource(options) {
+  const origin = chapiOrigin(options.baseUrl);
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const doFetch = (input, init) => (options.fetch ?? globalThis.fetch)(input, init);
+  function url(endpoint, query) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+      if (value !== void 0) params.set(key, String(value));
+    }
+    const qs = params.toString();
+    return `${origin}/v2/files${endpoint}${qs ? `?${qs}` : ""}`;
+  }
+  async function headers(accept) {
+    const out = { Accept: accept };
+    const extra = await options.getHeaders?.();
+    if (extra) Object.assign(out, extra);
+    const token = await options.getAccessToken?.();
+    if (token) out.Authorization = `Bearer ${token}`;
+    return out;
+  }
+  async function request(target, accept, signal, retried = false) {
+    if (signal?.aborted) throw signal.reason ?? new DOMException("Aborted", "AbortError");
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      controller.abort();
+    }, timeoutMs);
+    const onAbort = () => controller.abort();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    const release = () => clearTimeout(timer);
+    let res;
+    try {
+      const init = { headers: await headers(accept), signal: controller.signal };
+      if (controller.signal.aborted) throw new DOMException("Aborted", "AbortError");
+      res = await doFetch(target, init);
+    } catch (err) {
+      release();
+      signal?.removeEventListener("abort", onAbort);
+      if (signal?.aborted && isAbortError(err)) throw err;
+      if (signal?.aborted) throw new DOMException("Aborted", "AbortError");
+      if (timedOut) throw new FilesError("timeout", MESSAGES.timeout, { cause: err });
+      throw new FilesError("network", MESSAGES.network, { cause: err });
+    }
+    release();
+    if (res.status === 401 && !retried && options.onUnauthorized) {
+      await res.body?.cancel().catch(() => {
+      });
+      signal?.removeEventListener("abort", onAbort);
+      if (await options.onUnauthorized()) return request(target, accept, signal, true);
+      throw new FilesError("unauthorized", MESSAGES.unauthorized, { status: 401 });
+    }
+    if (!res.ok) {
+      signal?.removeEventListener("abort", onAbort);
+      throw await errorFromResponse(res);
+    }
+    return res;
+  }
+  async function json(target, signal) {
+    const res = await request(target, "application/json", signal);
+    try {
+      return await res.json();
+    } catch (err) {
+      if (signal?.aborted) throw err;
+      throw new FilesError("file_server_error", "The file server sent an unreadable reply.", {
+        status: res.status,
+        cause: err
+      });
+    }
+  }
+  return {
+    async listRoots(signal) {
+      const body = await json(url("/roots", {}), signal);
+      return (body.data ?? []).filter((r) => r && r.active !== false).map(rootFromChapi);
+    },
+    async list(rootId, path, opts = {}) {
+      const limit = opts.limit === void 0 ? void 0 : Math.min(MAX_PAGE_SIZE, Math.max(1, Math.floor(opts.limit)));
+      const body = await json(
+        url(`/roots/${encodeURIComponent(rootId)}/entries`, {
+          path: normalizePath(path),
+          limit,
+          cursor: opts.cursor || void 0,
+          includeHidden: opts.includeHidden ? true : void 0
+        }),
+        opts.signal
+      );
+      return {
+        entries: (body.data ?? []).map(entryFromChapi),
+        total: typeof body.meta?.total === "number" ? body.meta.total : void 0,
+        nextCursor: body.meta?.nextCursor || null
+      };
+    },
+    async info(rootId, path, signal) {
+      const body = await json(
+        url(`/roots/${encodeURIComponent(rootId)}/info`, { path: normalizePath(path) }),
+        signal
+      );
+      if (!body.data) {
+        throw new FilesError("file_server_error", "The file server sent an empty reply.");
+      }
+      return entryFromChapi(body.data);
+    },
+    async read(rootId, path, opts = {}) {
+      const res = await request(
+        url(`/roots/${encodeURIComponent(rootId)}/content`, {
+          path: normalizePath(path),
+          download: opts.download ? "true" : "false"
+        }),
+        "*/*",
+        opts.signal
+      );
+      try {
+        return await res.blob();
+      } catch (err) {
+        if (opts.signal?.aborted) throw err;
+        throw new FilesError("network", "The download was interrupted.", { cause: err });
+      }
+    }
+  };
+}
+
+// src/memory.ts
+var ENCODER = typeof TextEncoder === "undefined" ? void 0 : new TextEncoder();
+function contentSize(content) {
+  if (content === void 0 || typeof content === "function") return 0;
+  if (typeof content === "string") return ENCODER?.encode(content).length ?? content.length;
+  return content.size;
+}
+function encodeCursor(offset) {
+  return `c${offset.toString(36)}`;
+}
+function decodeCursor(cursor) {
+  const match = /^c([0-9a-z]+)$/.exec(cursor);
+  if (!match) throw new FilesError("invalid_cursor", "Invalid cursor.", { status: 400 });
+  return parseInt(match[1], 36);
+}
+function wait(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) return reject(new DOMException("Aborted", "AbortError"));
+    if (ms <= 0) return resolve();
+    const timer = setTimeout(done, ms);
+    function done() {
+      signal?.removeEventListener("abort", abort);
+      resolve();
+    }
+    function abort() {
+      clearTimeout(timer);
+      reject(new DOMException("Aborted", "AbortError"));
+    }
+    signal?.addEventListener("abort", abort, { once: true });
+  });
+}
+function createMemoryFilesSource(options) {
+  const defaultModified = options.now ?? (/* @__PURE__ */ new Date()).toISOString();
+  const roots = /* @__PURE__ */ new Map();
+  for (const { files, ...root } of options.roots) {
+    const nodes = /* @__PURE__ */ new Map();
+    const addDir = (path) => {
+      if (!path || nodes.has(path)) return;
+      addDir(parentPath(path));
+      nodes.set(path, {
+        entry: {
+          name: path.slice(path.lastIndexOf("/") + 1),
+          path,
+          type: "dir",
+          size: 0,
+          modified: defaultModified,
+          hidden: false
+        }
+      });
+    };
+    for (const file of files) {
+      const path = normalizePath(file.path);
+      if (!path) continue;
+      addDir(parentPath(path));
+      const type = file.type ?? "file";
+      const entry = {
+        name: path.slice(path.lastIndexOf("/") + 1),
+        path,
+        type,
+        size: type === "dir" ? 0 : file.size ?? contentSize(file.content),
+        modified: file.modified ?? defaultModified,
+        hidden: file.hidden ?? false
+      };
+      if (file.etag) entry.etag = file.etag;
+      nodes.set(path, { entry, content: file.content });
+    }
+    const explicit = new Set(files.filter((f) => f.modified).map((f) => normalizePath(f.path)));
+    const newest = /* @__PURE__ */ new Map();
+    for (const { entry } of nodes.values()) {
+      if (entry.type === "dir" && !explicit.has(entry.path)) continue;
+      for (let p = parentPath(entry.path); p; p = parentPath(p)) {
+        const current = newest.get(p);
+        if (!current || Date.parse(entry.modified) > Date.parse(current)) {
+          newest.set(p, entry.modified);
+        }
+      }
+    }
+    for (const [p, modified] of newest) {
+      const node = nodes.get(p);
+      if (node && node.entry.type === "dir" && !explicit.has(p)) node.entry.modified = modified;
+    }
+    roots.set(root.id, { root: { ...root }, nodes });
+  }
+  async function begin(request, signal) {
+    await wait(options.latency ?? 0, signal);
+    const failure = options.intercept?.(request);
+    if (failure) throw failure;
+  }
+  function rootOf(rootId) {
+    const root = roots.get(rootId);
+    if (!root) throw new FilesError("not_found", "Root not found.", { status: 404 });
+    return root;
+  }
+  function resolve(rootId, rawPath) {
+    const path = normalizePath(rawPath);
+    const { nodes } = rootOf(rootId);
+    const segments = path ? path.split("/") : [];
+    for (let i = 1; i < segments.length; i++) {
+      const ancestor = nodes.get(segments.slice(0, i).join("/"));
+      if (ancestor?.entry.type === "link") {
+        throw new FilesError("link_not_followed", "Links are not followed.", {
+          status: 403,
+          reason: "link_not_followed"
+        });
+      }
+    }
+    return path ? nodes.get(path) : void 0;
+  }
+  function children(rootId, path, includeHidden) {
+    const { nodes } = rootOf(rootId);
+    const out = [];
+    for (const node of nodes.values()) {
+      if (parentPath(node.entry.path) !== path || node.entry.path === "") continue;
+      if (!includeHidden && node.entry.hidden) continue;
+      out.push({ ...node.entry });
+    }
+    return out.sort(compareEntries);
+  }
+  function page(all, opts) {
+    const limit = Math.min(1e3, Math.max(1, opts.limit ?? options.defaultLimit ?? 200));
+    const offset = opts.cursor ? decodeCursor(opts.cursor) : 0;
+    if (offset > all.length)
+      throw new FilesError("invalid_cursor", "Invalid cursor.", { status: 400 });
+    const entries = all.slice(offset, offset + limit);
+    const next = offset + limit;
+    return {
+      entries,
+      total: all.length,
+      nextCursor: next < all.length ? encodeCursor(next) : null
+    };
+  }
+  const source = {
+    async listRoots(signal) {
+      await begin({ op: "listRoots" }, signal);
+      return [...roots.values()].map(({ root }) => ({ ...root }));
+    },
+    async list(rootId, rawPath, opts = {}) {
+      const path = normalizePath(rawPath);
+      await begin({ op: "list", rootId, path }, opts.signal);
+      const node = resolve(rootId, path);
+      if (path && !node) throw new FilesError("not_found", "Not found.", { status: 404 });
+      if (node?.entry.type === "link") {
+        throw new FilesError("link_not_followed", "Links are not followed.", {
+          status: 403,
+          reason: "link_not_followed"
+        });
+      }
+      if (node && node.entry.type !== "dir") {
+        throw new FilesError("not_a_directory", "Not a directory.", { status: 400 });
+      }
+      return page(children(rootId, path, !!opts.includeHidden), opts);
+    },
+    async info(rootId, rawPath, signal) {
+      const path = normalizePath(rawPath);
+      await begin({ op: "info", rootId, path }, signal);
+      if (!path) {
+        rootOf(rootId);
+        return {
+          name: "",
+          path: "",
+          type: "dir",
+          size: 0,
+          modified: defaultModified,
+          hidden: false
+        };
+      }
+      const node = resolve(rootId, path);
+      if (!node) throw new FilesError("not_found", "Not found.", { status: 404 });
+      return { ...node.entry };
+    },
+    async read(rootId, rawPath, opts = {}) {
+      const path = normalizePath(rawPath);
+      await begin({ op: "read", rootId, path }, opts.signal);
+      const node = resolve(rootId, path);
+      if (!node) throw new FilesError("not_found", "Not found.", { status: 404 });
+      if (node.entry.type === "link") {
+        throw new FilesError("link_not_followed", "Links are not followed.", {
+          status: 403,
+          reason: "link_not_followed"
+        });
+      }
+      if (node.entry.type === "dir") {
+        throw new FilesError("is_directory", "Is a directory.", { status: 400 });
+      }
+      const content = node.content;
+      if (typeof content === "function") return await content();
+      if (content instanceof Blob) return content;
+      return new Blob([content ?? ""], { type: "application/octet-stream" });
+    }
+  };
+  if (options.search) {
+    source.search = async (rootId, query, opts = {}) => {
+      const under = normalizePath(opts.path);
+      await begin({ op: "search", rootId, path: under }, opts.signal);
+      const { nodes } = rootOf(rootId);
+      const all = filterEntries(
+        [...nodes.values()].map((n) => n.entry).filter(
+          (e) => (opts.includeHidden || !e.hidden) && (under === "" || e.path.startsWith(`${under}/`))
+        ),
+        query
+      ).sort(compareEntries);
+      return page(
+        all.map((e) => ({ ...e })),
+        opts
+      );
+    };
+  }
+  return source;
+}
+
+export { BAD_REQUEST_REASONS, DEFAULT_PAGE_SIZE, DEFAULT_TIMEOUT_MS, FilesError, KIND_LABELS, MAX_PAGE_SIZE, NEVER_INLINE_EXTENSIONS, baseName, chapiOrigin, compareEntries, createChapiFilesSource, createMemoryFilesSource, describeFilesError, displayPath, entryFromChapi, fileExtension, filesErrorCode, filterEntries, formatBytes, formatDateTime, formatRelativeTime, isAbortError, isFilesError, isWithin, joinPath, kindForEntry, kindForName, normalizePath, parentPath, parseRetryAfter, pathSegments, previewRoute, rootFromChapi, saveBlob, sortEntries, writeCapabilities };

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "@classic-homes/files-core",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Framework-agnostic network-drive file browsing for Classic Theme: the FilesSource interface, the CHAPI /v2/files adapter, an in-memory source, path, sort and format helpers, and typed errors",
+  "type": "module",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "node ../../scripts/rm.mjs dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "vitest": "^4.1.10"
+  },
+  "keywords": [
+    "file-browser",
+    "network-drive",
+    "smb",
+    "chapi",
+    "classic-theme"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Classic-Homes/classic-theme.git",
+    "directory": "packages/files-core"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}