@nonext/husk 0.2.3

package/dist/firebase/index.d.ts

@@ -0,0 +1,251 @@
+import { Firestore } from 'firebase/firestore';
+import { C as CmsAdapter, g as MediaAdapter } from '../adapter-C_0mhENy.js';
+import { R as Registry } from '../registry-CUC25qay.js';
+import { r as WriteRateLimiter, l as MediaRejection } from '../write-limits-Djmm6L3R.js';
+import { f as FieldTypeRegistry } from '../field-type-D25Vojb0.js';
+import { b as AuthUser } from '../auth-B2gBtHl5.js';
+export { A as AuthError, a as AuthErrorCode, C as ClaimSet, b as ClaimSync, c as ClaimSyncError, E as EmulatorClaimSyncOptions, H as HuskAuth, d as HuskAuthDeps, N as NewUser, S as SignUpInput, e as StoredUser, U as UserPatch, f as createEmulatorClaimSync, g as createHuskAuth, h as createUnavailableClaimSync, p as patchUser, r as readUser, t as toAuthUser, w as writeUser } from '../index-5ylaMBUH.js';
+import { FirebaseStorage } from 'firebase/storage';
+import { M as MediaItem } from '../field-Diyf5siF.js';
+import '../entry-D3kiE8T1.js';
+import 'react';
+import 'firebase/auth';
+
+interface FirestoreAdapterDeps {
+    db: Firestore;
+    /**
+     * The live registry. Supplied by the CMS instance, which owns it: the adapter must not
+     * build one, because the registry is assembled from code-defined types the adapter cannot
+     * see plus stored ones it reads through `schemas`.
+     *
+     * A function rather than a value, because the database half changes while the admin runs
+     * and every call has to see the current merge. It is also what makes the lock guard
+     * structural: an adapter cannot be constructed without the registry that says which types
+     * are code-defined and which are locked, so `schemas.update` and `schemas.delete` always
+     * have the answer available and never have to trust the caller for it.
+     */
+    registry: () => Registry;
+    currentUser: () => AuthUser;
+    /**
+     * The session, for read-side permission checks. Optional, and its absence is meaningful.
+     *
+     * `currentUser` is the write path's account and throws on a connection that has none,
+     * which is what proves a public page never asks who is reading. So the read check gets
+     * its own accessor: the admin passes one and its `list`, `get` and `count` are refused
+     * for a content type this account may not read, while a customer's website omits it and
+     * the read path stays free of any question about a session. The security rules refuse a
+     * denied read either way; this is the layer that refuses it before the round trip.
+     */
+    session?: () => AuthUser | null;
+    /** Field type specs. Optional until M5; the converters fall back to defaults without it. */
+    fieldTypes?: FieldTypeRegistry;
+    /**
+     * The burst guard for this adapter, or `null` for a process that is legitimately a bulk
+     * writer: the seed loader, a migration run, a one-off import.
+     *
+     * Passing `null` is a statement, not a convenience. It says "the thing the burst guard
+     * exists to catch is exactly what this process is doing", and it gives up nothing the
+     * security rules enforce, because the rules-side floor is per document and this guard is
+     * per process. See core/write-limits.ts.
+     */
+    rateLimiter?: WriteRateLimiter | null;
+}
+declare function createFirestoreAdapter(deps: FirestoreAdapterDeps): CmsAdapter;
+
+/**
+ * How the media library starts an upload, without knowing that Storage exists.
+ *
+ * The same seam as `RelationSource` for the relation picker, and for the same reason: the
+ * screen lives under `src/admin/**`, where the Firebase SDK may not be imported, and it
+ * still has to offer progress, cancel and retry. The host builds one with
+ * `createMediaUploader` from `@nonext/husk/firebase` and hands it in.
+ *
+ * Every member below mirrors what `createMediaUpload` already returns, so the real
+ * implementation is a pass-through and a test implementation is a few lines.
+ */
+type MediaUploadPhase = "idle" | "uploading" | "storing" | "done" | "cancelled" | "failed";
+interface MediaUploadProgress {
+    phase: MediaUploadPhase;
+    bytesTransferred: number;
+    totalBytes: number;
+    /** 0 to 1. Exactly 1 only once every byte is acknowledged. */
+    fraction: number;
+    /** 1 for the first run, 2 for the first retry, and so on. */
+    attempt: number;
+}
+interface MediaUploadHandle {
+    readonly mediaId: string;
+    readonly path: string;
+    readonly fileName: string;
+    progress(): MediaUploadProgress;
+    start(): Promise<MediaItem>;
+    /** Runs it again to the same id and the same path, so remains are overwritten. */
+    retry(): Promise<MediaItem>;
+    cancel(): void;
+}
+interface MediaUploadRequest {
+    onProgress?: (progress: MediaUploadProgress) => void;
+    alt?: string | null;
+}
+interface MediaUploader {
+    create(file: File, options?: MediaUploadRequest): MediaUploadHandle;
+    /**
+     * New bytes for an item that already exists, keeping its id and its object path.
+     *
+     * The MIME type may not change: the path is fixed for the life of the item and the rules
+     * tie the path's extension to the declared type. The implementation refuses a mismatch
+     * with a sentence rather than letting it surface as a permission error.
+     */
+    replace(existing: MediaItem, file: File, options?: MediaUploadRequest): MediaUploadHandle;
+}
+
+/**
+ * Uploading one file into the media library.
+ *
+ * An upload is two writes that cannot be made atomic: the bytes go to Storage, the metadata
+ * document goes to Firestore, and no transaction spans the two. The order is therefore a
+ * decision rather than an accident, and it is this one: **bytes first, document last**.
+ *
+ * - A document written before the bytes would point at an object that does not exist. The
+ *   library would list it, the picker would offer it, an entry could reference it, and a
+ *   visitor would get a broken image on the customer's site. The failure would be visible
+ *   everywhere except where it happened.
+ * - An object written before the document is invisible to the CMS, because the CMS lists
+ *   documents, not bucket contents. It costs storage and nothing else, and M7's orphan
+ *   sweep is defined precisely as "an object with no document".
+ *
+ * So when the document write fails after the bytes landed, this module tries to delete the
+ * object it just wrote (see `removeOrphan`). If that cleanup also fails, the upload does not
+ * pretend to have been clean: the thrown `MediaUploadError` carries `orphanedPath`, naming
+ * the object still sitting in the bucket, so the admin can say so and the sweep has a
+ * starting point. Nothing is swallowed and nothing is guessed.
+ *
+ * What this module still cannot cover: a browser closed between the two writes. That leaves
+ * an orphan no client will ever clean up, which is the reason the sweep exists rather than
+ * being a nice-to-have.
+ */
+type UploadPhase = "idle" | "uploading" | "storing" | "done" | "cancelled" | "failed";
+interface UploadProgress {
+    phase: UploadPhase;
+    bytesTransferred: number;
+    totalBytes: number;
+    /** 0 to 1. Exactly 1 only once every byte is acknowledged by Storage. */
+    fraction: number;
+    /** 1 for the first run, 2 for the first retry, and so on. */
+    attempt: number;
+}
+interface ImageSize {
+    width: number;
+    height: number;
+}
+/**
+ * Reads the pixel size of an image, or returns null when it cannot.
+ *
+ * Injected rather than imported so the upload path stays testable without a DOM, and so a
+ * host that has a better decoder than the browser can supply one.
+ */
+type ImageSizeReader = (file: Blob, type: string) => Promise<ImageSize | null>;
+interface MediaUploadDeps {
+    storage: FirebaseStorage;
+    media: MediaAdapter;
+    /** Whose upload this is. Written into the object's custom metadata; see storage.rules. */
+    currentUser: () => AuthUser;
+    /** Defaults to `browserImageSize`. */
+    readImageSize?: ImageSizeReader;
+}
+interface MediaUploadOptions {
+    onProgress?: (progress: UploadProgress) => void;
+    /** Alt text captured in the upload form, if any. Editable afterwards. */
+    alt?: string | null;
+}
+type MediaUploadErrorCode = "rejected" | "cancelled" | "storage-failed" | "metadata-failed";
+declare class MediaUploadError extends Error {
+    readonly name = "MediaUploadError";
+    readonly code: MediaUploadErrorCode;
+    /** Set when the file itself was refused, so the UI can point at the offending rule. */
+    readonly rejection: MediaRejection | null;
+    /**
+     * The Storage object that outlived the failed upload, when cleanup could not remove it.
+     * Null means nothing was left behind, which is the ordinary case.
+     */
+    readonly orphanedPath: string | null;
+    constructor(code: MediaUploadErrorCode, message: string, detail?: {
+        rejection?: MediaRejection;
+        orphanedPath?: string;
+        cause?: unknown;
+    });
+}
+interface MediaUpload {
+    /** Allocated before anything is written, because the object path contains it. */
+    readonly mediaId: string;
+    /** The Storage object path this upload writes to, on every attempt. */
+    readonly path: string;
+    readonly fileName: string;
+    progress(): UploadProgress;
+    /** Runs the upload. Rejects with `MediaUploadError`; resolves with the stored item. */
+    start(): Promise<MediaItem>;
+    /**
+     * Runs it again after a failure or a cancellation, to the same id and the same path, so
+     * a retried upload overwrites its own remains instead of accumulating them.
+     */
+    retry(): Promise<MediaItem>;
+    /** Aborts an attempt in flight. A no-op before the first attempt and after success. */
+    cancel(): void;
+}
+/** Prepares an upload without starting it, which is what gives the caller a cancel handle. */
+declare function createMediaUpload(deps: MediaUploadDeps, file: File, options?: MediaUploadOptions): MediaUpload;
+/**
+ * Replacing the bytes of an item that is already in the library.
+ *
+ * Replace keeps the media id and the Storage object path, which is what makes it a replace
+ * rather than a delete followed by an upload: every entry that references the item goes on
+ * referencing the same item, and no reference has to be repaired by hand.
+ *
+ * Keeping the path has one consequence that is a rule rather than an accident: the
+ * replacement must be of the same MIME type as the original. The object path ends in the
+ * file name, `storage.rules` requires the name's extension to match the declared content
+ * type, and `firestore.rules` forbids a media document's `path` from ever changing. A JPEG
+ * cannot therefore take the place of a PNG. That is refused here, with a sentence, rather
+ * than left to surface as a permission error.
+ *
+ * What the caller must do afterwards, and what this function deliberately does not do:
+ * overwriting an object mints a new download URL, so the `url` denormalized into every
+ * referencing entry is now stale. `media.refreshReferences(mediaId, url)` rewrites them.
+ * It is a separate call because it is a batch of entry writes with its own partial-failure
+ * story, and burying that inside an upload handle would hide it.
+ *
+ * The one state it cannot make safe: if the bytes land and the document update fails, the
+ * object holds the new file while the record still describes the old one, and the old url
+ * is already dead. There is nothing to compensate with, because deleting the object would
+ * destroy the item outright. The error says so plainly and asks for another attempt.
+ */
+declare function createMediaReplace(deps: MediaUploadDeps, existing: MediaItem, file: File, options?: MediaUploadOptions): MediaUpload;
+/** Prepares and starts an upload in one call, for callers with nothing to cancel. */
+declare function uploadMedia(deps: MediaUploadDeps, file: File, options?: MediaUploadOptions): Promise<MediaItem>;
+/**
+ * Deletes an object left behind by a half-finished upload. Reports whether it is gone.
+ *
+ * True means the bucket confirmed it: the delete succeeded, or the object was already
+ * reported missing. Anything else, a permission denial above all, is false, so the caller
+ * names the path instead of claiming a cleanup that did not happen.
+ *
+ * One asymmetry worth knowing, because it looks like a bug from the outside: the storage
+ * rules let an author delete only an object whose custom metadata names them, and a path
+ * with no object has no metadata to name anyone. An author asking to remove something that
+ * was never there is therefore denied rather than told it is missing, and gets false. That
+ * is the safe direction: the only caller is the compensating delete after a failed metadata
+ * write, where the object demonstrably exists and belongs to the caller.
+ */
+declare function removeOrphan(storage: FirebaseStorage, path: string): Promise<boolean>;
+/** The default reader. Returns null wherever `createImageBitmap` is unavailable. */
+declare const browserImageSize: ImageSizeReader;
+/**
+ * The upload seam the admin is written against.
+ *
+ * The media library screen starts, cancels and retries uploads, and it lives under
+ * `src/admin/**`, where Firebase may not be imported. It therefore takes a `MediaUploader`
+ * and the host builds one here, exactly as the relation picker takes a `RelationSource`.
+ */
+declare function createMediaUploader(deps: MediaUploadDeps): MediaUploader;
+
+export { type FirestoreAdapterDeps, type ImageSize, type ImageSizeReader, type MediaUpload, type MediaUploadDeps, MediaUploadError, type MediaUploadErrorCode, type MediaUploadOptions, type UploadPhase, type UploadProgress, browserImageSize, createFirestoreAdapter, createMediaReplace, createMediaUpload, createMediaUploader, removeOrphan, uploadMedia };