@buildinternet/uploads 0.42.0 → 0.42.2

package/dist/comment-render.generated.d.ts

@@ -0,0 +1,151 @@
+/**
+ * GENERATED by packages/uploads/scripts/inline-shared.mjs — do not edit.
+ * Canonical source: packages/comment-render/src/index.ts
+ * The published CLI cannot import private @uploads/* packages, so this file
+ * is inlined into the tarball. Re-run the script after changing the source.
+ */
+export type GhTargetKind = "pull" | "issues";
+export interface GhTarget {
+    /** "owner/name" */
+    repo: string;
+    kind: GhTargetKind;
+    num: number;
+}
+/** Non-safe chars → `-` for a single R2 key segment (owner/name/branch/…).
+ * Exported for reuse by other GitHub-key builders (github-ingest.ts) that
+ * need the identical sanitization rule — github-promote.ts keeps its own
+ * byte-identical private copy rather than importing this one. */
+export declare function sanitizeKeySegment(s: string): string;
+export declare function ghKeyPrefix(target: GhTarget): string;
+/** Literal root under which every private-repo attachment key lives. */
+export declare const GH_PRIVATE_ROOT = "gh/private/";
+/**
+ * Private-repo key prefix: `gh/private/<32-hex-id>/<kind>/<num>/`.
+ * Deliberately omits the repo (unlike `ghKeyPrefix`) — the id is a random,
+ * unguessable per-repo prefix rather than an owner/name path, so callers
+ * that need the repo back must read `gh.repo` metadata (see
+ * `parseGhPrivateKey`, which cannot recover it from the key alone).
+ */
+export declare function ghPrivateKeyPrefix(prefixId: string, target: GhTarget): string;
+/** Private-repo attachment key: `ghPrivateKeyPrefix` + the sanitized filename. */
+export declare function ghPrivateAttachmentKey(prefixId: string, target: GhTarget, filename: string): string;
+/**
+ * Private-repo branch-staged key prefix: `gh/private/<32-hex-id>/branch/`.
+ * Unlike `ghBranchKeyPrefix`, there is deliberately NO branch-name segment —
+ * the branch name itself is not embedded in a private-repo key.
+ */
+export declare function ghPrivateBranchKeyPrefix(prefixId: string): string;
+/** Private-repo branch-staged attachment key: `ghPrivateBranchKeyPrefix` + the sanitized filename. */
+export declare function ghPrivateBranchAttachmentKey(prefixId: string, filename: string): string;
+/**
+ * Inverse of `ghPrivateKeyPrefix`: parse the prefix id/kind/number back out
+ * of a private-repo attachment key, or undefined for any other key shape.
+ * Cannot recover the repo — callers that need it read `gh.repo` metadata.
+ */
+export declare function parseGhPrivateKey(key: string): {
+    prefixId: string;
+    kind: GhTargetKind;
+    num: number;
+} | undefined;
+/** Hidden marker identifying the one comment this CLI manages. Never change it — existing comments are found by exact match. */
+export declare const ATTACHMENTS_MARKER = "<!-- uploads.sh:attachments -->";
+/**
+ * Per-workspace marker (`<!-- uploads.sh:attachments ws=<workspace> -->`) so
+ * two workspaces managing the same repo don't clobber each other's comment.
+ * Falls back to the shared legacy marker when `workspace` is missing or does
+ * not look like a safe slug — degrade, don't guess or risk breaking the
+ * comment's HTML.
+ */
+export declare function attachmentsMarker(workspace?: string): string;
+/** Max attachments embedded as inline `<img>` tags before the rest collapse
+ * into a `<details>` link list. Keeps very large threads from becoming a wall
+ * of images. */
+export declare const MAX_INLINE_ATTACHMENT_IMAGES = 16;
+/**
+ * Per-render knobs for the managed comment (issue #307), sourced from repo
+ * comment config. `imageWidth: "auto"` uses per-item filename heuristics plus
+ * density-aware sizing (solo/sparse/dense from the inlined count); `"full"`
+ * omits the `width` attribute entirely; a number overrides every width site.
+ */
+export interface CommentRenderOptions {
+    imageWidth: "auto" | "full" | number;
+    maxInlineImages: number;
+    metaPath: boolean;
+    metaState: boolean;
+    note: string | null;
+}
+/** Today's behavior, expressed as options — the default for every caller that
+ * hasn't opted into repo comment config. */
+export declare const AUTO_RENDER_OPTIONS: CommentRenderOptions;
+export interface AttachmentItem {
+    key: string;
+    url: string | null;
+    /** Prefer for `<img src>` on GitHub (Camo-friendly host). Falls back to `url`. */
+    embedUrl?: string | null;
+    /** Canonical `/f/` file-page URL (server-computed). Preferred click-through target; falls back to `url`. */
+    pageUrl?: string | null;
+    /**
+     * The only canonical metadata the managed comment renders (issue #365).
+     * Deliberately two named fields rather than `Record<string, string>`: the
+     * comment is posted publicly, and keeping the set narrow at the type level
+     * mirrors the server-side query filter that never fetches EXIF-derived
+     * keys like `device`/`software` for this path.
+     */
+    meta?: {
+        path?: string;
+        state?: string;
+    };
+    /**
+     * Poster frame for a video (issue #299), server-computed like `embedUrl` —
+     * never taken from client-settable metadata. Absent means "no poster", and
+     * the renderer falls back to the bullet link.
+     */
+    posterUrl?: string | null;
+    /** Derived video facts used for the caption and display width. */
+    videoMeta?: {
+        durationSeconds?: number;
+        width?: number;
+        height?: number;
+    };
+}
+/** A public gallery linked to the PR or issue whose managed comment is syncing. */
+export interface GalleryCommentItem {
+    title: string;
+    /** Canonical URL returned by the API; callers must not synthesize it. */
+    url: string;
+    /** A bounded set of available images; each links to its item page when known, else the gallery. */
+    previews?: {
+        url: string;
+        alt: string;
+        embedUrl?: string | null;
+        itemUrl?: string;
+    }[];
+}
+/**
+ * How crowded the managed comment is. Sparse comments (one shot, a single
+ * before/after) get larger embeds; dense comments keep compact historical sizes.
+ */
+export type AttachmentDensity = "solo" | "sparse" | "dense";
+/** Dense (historical) default max width for images in the managed comment. */
+export declare const ATTACHMENT_IMAGE_WIDTH_DEFAULT = 400;
+/** Portrait / device mockups — keep phones readable, not full-column. */
+export declare const ATTACHMENT_IMAGE_WIDTH_PORTRAIT = 280;
+/** Wide UI / browser chrome. */
+export declare const ATTACHMENT_IMAGE_WIDTH_WIDE = 640;
+/** Dense pair-cell cap (side-by-side before/after). */
+export declare const ATTACHMENT_IMAGE_WIDTH_PAIR = 320;
+/** Map an inlined-media count onto a density tier. */
+export declare function attachmentDensityForCount(inlinedCount: number): AttachmentDensity;
+/** Pair-cell cap for the given density. */
+export declare function attachmentPairWidth(density?: AttachmentDensity): number;
+/**
+ * Display width for a GitHub comment embed. Filenames are a weak but practical
+ * signal (we don't re-fetch dimensions when rebuilding the comment). `density`
+ * only affects managed-comment auto layout; other callers leave it `"dense"`.
+ */
+export declare function attachmentImageWidth(filename: string, density?: AttachmentDensity): number;
+/**
+ * Render the one marker-owned GitHub comment. When there are no galleries this
+ * intentionally preserves the legacy attachment-only body byte-for-byte.
+ */
+export declare function attachmentsCommentBody(items: AttachmentItem[], galleries?: GalleryCommentItem[], marker?: string, options?: CommentRenderOptions): string;