emdash-emit 0.1.7 → 0.1.9

package/dist/client/media.d.ts

@@ -0,0 +1,141 @@
+import type { CacheDatabase } from '../db/cache.js';
+/**
+ * Maximum media upload size allowed by EmDash OpenAPI 3.1.0 schema (MediaUploadUrlBody.size.maximum).
+ * 50 MiB = 52,428,800 bytes.
+ */
+export declare const MAX_MEDIA_UPLOAD_BYTES = 52428800;
+export declare function resolveImageMimeType(filename: string): string | null;
+export interface MediaHashes {
+    /** Emit-internal SHA-256 hex key used exclusively for local media_state table */
+    localHash: string;
+    /** EmDash server deduplication hash formatted as "sha1:<40-char-hex>" */
+    serverContentHash: string;
+}
+export declare function computeMediaHashes(buffer: Buffer): MediaHashes;
+/**
+ * Normalizes a media file URL into the canonical root-relative form:
+ * `/_emdash/api/media/file/<storageKey>`
+ *
+ * Note: `storageKey` may be either `<ULID>.<ext>` (legacy migrated media) or
+ * `<ULID_1>.<ULID_2>.<ext>` (native EmDash uploads after confirmation). Treat it as an opaque key.
+ */
+export declare function toRootRelativeMediaUrl(rawUrl: string | undefined | null, storageKey: string, origin: string): string;
+export interface MediaUploadUrlResponse {
+    uploadUrl: string;
+    method: 'PUT';
+    headers: Record<string, string>;
+    mediaId: string;
+    storageKey: string;
+    expiresAt: string;
+}
+export interface MediaExistingResponse {
+    existing: true;
+    mediaId: string;
+    storageKey: string;
+    url: string;
+}
+export interface UploadMediaOptions {
+    filePath?: string;
+    buffer?: Buffer;
+    filename: string;
+    contentType?: string;
+    origin: string;
+    token: string;
+    refreshToken?: string;
+    alt?: string;
+    caption?: string;
+    cache?: CacheDatabase;
+    fetchFn?: typeof fetch;
+}
+export interface UploadMediaResult {
+    /** Media record ULID (used for frontmatter `featuredImage` and promoted filename prefix) */
+    mediaId: string;
+    /** Confirmed storage key (used for `/_emdash/api/media/file/<storageKey>`) */
+    storageKey: string;
+    /** Canonical root-relative URL `/_emdash/api/media/file/<storageKey>` */
+    url: string;
+    /** SHA-256 hex of the binary file */
+    localHash: string;
+    /** `sha1:<hex>` content hash */
+    contentHash: string;
+    size: number;
+    mimeType: string;
+    filename: string;
+    width?: number | null;
+    height?: number | null;
+    createdAt?: string;
+    deduplicated: boolean;
+    /**
+     * Whether the returned record was confirmed against `GET /_emdash/api/media/{mediaId}`.
+     * - `'verified'`: the remote record was confirmed to exist and be `ready`
+     * - `'unknown'`: the server did not answer the existence check (no GET support / 5xx / network error)
+     * Absent for a fresh upload confirmed via `POST .../confirm`.
+     */
+    remoteVerification?: 'verified' | 'unknown';
+    /** Reason attached when `remoteVerification` is `'unknown'` */
+    remoteVerificationNote?: string;
+}
+export interface CompensationResult {
+    compensated: boolean;
+    alreadyReadyItem?: Record<string, unknown>;
+}
+export interface RemoteMediaDetail {
+    id: string;
+    filename?: string;
+    mimeType?: string;
+    size?: number;
+    width?: number | null;
+    height?: number | null;
+    alt?: string | null;
+    caption?: string | null;
+    storageKey?: string;
+    contentHash?: string | null;
+    status?: string;
+    createdAt?: string;
+    url?: string;
+}
+/**
+ * Result of a remote media existence check. `'unknown'` always carries a human-readable
+ * `reason` so callers can surface it as a warning instead of silently treating the record
+ * as verified.
+ */
+export type RemoteMediaExistence = {
+    exists: true;
+    item: RemoteMediaDetail;
+} | {
+    exists: false;
+} | {
+    exists: 'unknown';
+    reason: string;
+};
+/**
+ * Fetches authoritative metadata for a single media record via `GET /_emdash/api/media/{mediaId}`.
+ * Returns:
+ * - `{ exists: true, item }` when the server returns 200 OK
+ * - `{ exists: false }` when the server returns 404 Not Found (deleted on remote)
+ * - `{ exists: 'unknown', reason }` on transient errors or when the server does not implement GET
+ */
+export declare function fetchRemoteMediaDetail(mediaId: string, options: {
+    origin: string;
+    token: string;
+    fetchFn: typeof fetch;
+}): Promise<RemoteMediaExistence>;
+/**
+ * Compensating transaction for failed uploads after `POST /_emdash/api/media/upload-url`
+ * has created a pending record on the server.
+ *
+ * 1. Reads `GET /_emdash/api/media/{mediaId}` to inspect `status`.
+ * 2. If `status` is `pending` or `failed`, calls `DELETE /_emdash/api/media/{mediaId}`.
+ * 3. If `status` is `ready`, preserves the record and returns `alreadyReadyItem`.
+ */
+export declare function compensateOrphanMedia(mediaId: string, options: {
+    origin: string;
+    token: string;
+    fetchFn: typeof fetch;
+}): Promise<CompensationResult>;
+/**
+ * Executes the confirmed 4-phase EmDash media upload contract with server-side
+ * deduplication, local `media_state` idempotency, and orphan-pending compensation.
+ */
+export declare function uploadMediaFile(options: UploadMediaOptions): Promise<UploadMediaResult>;
+//# sourceMappingURL=media.d.ts.map

package/dist/client/media.d.ts.map

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