@buildinternet/uploads 0.29.0 → 0.30.0

package/dist/client.d.ts

@@ -82,6 +82,24 @@ export interface PutResult {
      * non-`gh/` key, existing object, no `replace`) instead of overwriting.
      */
     wouldRefuse?: boolean;
+    /**
+     * The object's R2 provenance bag (`client`, `source-name`,
+     * `content-sha256`) — what the upload was made *by*, not the tags it was
+     * tagged *with*. Absent on a dry run, and on API deployments older than the
+     * split that gave this bag its own name.
+     */
+    provenance?: Record<string, string>;
+    /**
+     * The queryable metadata (D1) this put stored, including server-derived
+     * pairs the client never sent (`gh.uploader`). Absent when the put carried
+     * no metadata — that case leaves any existing tags untouched, so the server
+     * reports nothing rather than implying an empty set. Means the same thing
+     * on `getMetadata`, `patchMetadata`, and `list({ metadata: true })`.
+     *
+     * An API older than the split returns the provenance bag here instead, so a
+     * client that must work against both reads `path`-style tags defensively —
+     * see `pathMetaHintFor` in commands.ts, which prefers what it sent.
+     */
     metadata?: Record<string, string>;
 }
 export interface ListItem {
@@ -106,7 +124,12 @@ export interface HeadResult {
     size: number;
     contentType: string;
     uploaded?: string;
-    metadata?: Record<string, string>;
+    /**
+     * The object's R2 provenance bag — see `PutResult.provenance`. A plain head
+     * returns no queryable metadata at all: that tier lives in a separate store
+     * and takes a separate read, so call `getMetadata(key)` for it.
+     */
+    provenance?: Record<string, string>;
 }
 export interface DeleteResult {
     key: string;

package/dist/commands.d.ts

@@ -123,6 +123,13 @@ export interface UploadPreparedImageResult {
     result: PutResult;
     prepared: PreparedUpload;
     markdown: string;
+    /**
+     * The queryable metadata this upload actually sent — `opts.metadata` after
+     * any derived image facts were merged in. Callers that need to reason about
+     * what was stored (see `pathMetaHintFor`) must read this, not
+     * `result.metadata`, which is the API's R2 provenance echo.
+     */
+    sentMetadata?: Record<string, string>;
 }
 /**
  * Shared bytes-oriented upload tail: frame + optimize the bytes, resolve the
@@ -182,15 +189,22 @@ export declare function syncAttachmentsComment(client: UploadsClient, target: Gh
  * (same tier as `state=`), and unlike `uploads screenshot` (which derives it
  * from the captured URL), a plain `attach`/`put --pr`/`put --issue` of an
  * already-existing image has nothing to derive it from, so it's easy to
- * forget. Fires once per batch (not per file) — checks the metadata the
- * server actually stored (`PutResult.metadata`), not what was requested, so
- * a merge/validation drop still surfaces the gap. Non-image uploads (zips,
+ * forget. Fires once per batch (not per file). Non-image uploads (zips,
  * PDFs, etc.) are exempt — "findable by page" doesn't apply to them.
+ *
+ * Checks the *resolved* metadata each upload actually sent (`--meta` pairs +
+ * sidecar manifest + derived image facts, index-aligned with `uploads`) —
+ * NOT `PutResult.metadata`. That field is the API's echo of the object's R2
+ * provenance bag (`client`, `source-name`, `content-sha256`, `uploaded-at`),
+ * never the queryable D1 tags, so it can't answer this question: reading it
+ * made the tip fire on every image, including ones uploaded with an explicit
+ * `--meta path=` (PR #509).
  */
-export declare function pathMetaHintFor(uploads: {
+export declare function pathMetaHintFor(uploads: readonly {
     contentType: string;
-    metadata?: Record<string, string>;
-}[]): string | undefined;
+}[], 
+/** Index-aligned with `uploads` — see `uploadPuts`/`uploadAttachments`. */
+sentMetadata: readonly (Record<string, string> | undefined)[]): string | undefined;
 export type AttachUploadItem = PutResult & {
     file: string;
     markdown: string;
@@ -211,6 +225,20 @@ export type AttachFailure = {
         status?: number;
     };
 };
+/** Shared shape of every prepare + put batch (`uploadPuts`/`uploadAttachments`). */
+export interface UploadBatchResult<T> {
+    uploads: T[];
+    failures: AttachFailure[];
+    /** The original cause of the first failure — for rethrowing single-file CLI paths. */
+    firstError?: unknown;
+    /**
+     * Index-aligned with `uploads`: the queryable metadata each upload actually
+     * sent (flags + sidecar + derived image facts). Kept beside the items rather
+     * than on them so it stays out of the `--format json` upload objects, which
+     * spread the item wholesale. See `pathMetaHintFor`.
+     */
+    sentMetadata: (Record<string, string> | undefined)[];
+}
 /**
  * Prepare + put each path as a PR/issue attachment with bounded concurrency.
  * Per-file errors collect in `failures` (does not throw). `firstError` is the
@@ -233,11 +261,7 @@ export declare function uploadAttachments(opts: {
     /** Provenance `client` field (default uploads-cli). */
     provenanceClient?: string;
     concurrency?: number;
-}): Promise<{
-    uploads: AttachUploadItem[];
-    failures: AttachFailure[];
-    firstError?: unknown;
-}>;
+}): Promise<UploadBatchResult<AttachUploadItem>>;
 /** A branch to stage attachments against pre-PR (`uploads attach --branch`). */
 export interface BranchTarget {
     repo: string;
@@ -266,11 +290,7 @@ export declare function uploadBranchAttachments(opts: {
     deriveImageFacts?: boolean;
     provenanceClient?: string;
     concurrency?: number;
-}): Promise<{
-    uploads: AttachUploadItem[];
-    failures: AttachFailure[];
-    firstError?: unknown;
-}>;
+}): Promise<UploadBatchResult<AttachUploadItem>>;
 export type PutUploadItem = PutResult & {
     file: string;
     markdown: string;
@@ -317,11 +337,7 @@ export declare function uploadPuts(opts: {
     alt?: string;
     width?: number;
     concurrency?: number;
-}): Promise<{
-    uploads: PutUploadItem[];
-    failures: AttachFailure[];
-    firstError?: unknown;
-}>;
+}): Promise<UploadBatchResult<PutUploadItem>>;
 export declare function runAttach(ctx: CliContext, args: string[], help?: boolean, run?: CommandRunner): Promise<number>;
 /**
  * One source of truth for the "staged, but not going to auto-attach" advisory

package/dist/commands.js

@@ -410,7 +410,7 @@ export async function uploadPreparedImage(client, bytes, sourceName, opts) {
         alt: opts.alt(prepared),
         width: opts.width,
     });
-    return { result, prepared, markdown };
+    return { result, prepared, markdown, sentMetadata: metadata };
 }
 export function frameOptionsFromFlags(flags) {
     const raw = flagString(flags, "--frame");
@@ -647,13 +647,21 @@ Examples:
  * (same tier as `state=`), and unlike `uploads screenshot` (which derives it
  * from the captured URL), a plain `attach`/`put --pr`/`put --issue` of an
  * already-existing image has nothing to derive it from, so it's easy to
- * forget. Fires once per batch (not per file) — checks the metadata the
- * server actually stored (`PutResult.metadata`), not what was requested, so
- * a merge/validation drop still surfaces the gap. Non-image uploads (zips,
+ * forget. Fires once per batch (not per file). Non-image uploads (zips,
  * PDFs, etc.) are exempt — "findable by page" doesn't apply to them.
+ *
+ * Checks the *resolved* metadata each upload actually sent (`--meta` pairs +
+ * sidecar manifest + derived image facts, index-aligned with `uploads`) —
+ * NOT `PutResult.metadata`. That field is the API's echo of the object's R2
+ * provenance bag (`client`, `source-name`, `content-sha256`, `uploaded-at`),
+ * never the queryable D1 tags, so it can't answer this question: reading it
+ * made the tip fire on every image, including ones uploaded with an explicit
+ * `--meta path=` (PR #509).
  */
-export function pathMetaHintFor(uploads) {
-    const missingPath = uploads.some((u) => u.contentType.startsWith("image/") && !u.metadata?.path);
+export function pathMetaHintFor(uploads, 
+/** Index-aligned with `uploads` — see `uploadPuts`/`uploadAttachments`. */
+sentMetadata) {
+    const missingPath = uploads.some((u, i) => u.contentType.startsWith("image/") && !sentMetadata[i]?.path);
     return missingPath ? "tip: add --meta path=/route so this shot is findable by page" : undefined;
 }
 /**
@@ -697,6 +705,7 @@ async function uploadAttachmentBatch(opts) {
             });
             return {
                 ok: true,
+                sentMetadata: metadata,
                 upload: {
                     ...result,
                     file,
@@ -719,17 +728,21 @@ async function uploadAttachmentBatch(opts) {
         }
     });
     const uploads = [];
+    const sentMetadata = [];
     const failures = [];
     let firstError;
     for (const slot of slots) {
-        if (slot.ok)
+        // Pushed together so the two arrays stay index-aligned across failures.
+        if (slot.ok) {
             uploads.push(slot.upload);
+            sentMetadata.push(slot.sentMetadata);
+        }
         else {
             firstError ??= slot.err;
             failures.push({ file: slot.file, error: errorDetail(slot.err) });
         }
     }
-    return { uploads, failures, firstError };
+    return { uploads, failures, firstError, sentMetadata };
 }
 /**
  * Prepare + put each path as a PR/issue attachment with bounded concurrency.
@@ -786,7 +799,7 @@ export async function uploadPuts(opts) {
             // Sidecar manifest from a prior `screenshot --out` of this exact file
             // (issue #469 lever 2) — see mergeSidecarMeta. Not applicable to stdin.
             const metadata = file !== "-" ? mergeSidecarMeta(file, bytes, opts.metadata) : opts.metadata;
-            const { result, prepared, markdown } = await uploadPreparedImage(opts.client, bytes, sourceName, {
+            const { result, prepared, markdown, sentMetadata } = await uploadPreparedImage(opts.client, bytes, sourceName, {
                 frame: opts.frame,
                 optimize: opts.optimize,
                 ghTarget: opts.ghTarget,
@@ -807,6 +820,7 @@ export async function uploadPuts(opts) {
             });
             return {
                 ok: true,
+                sentMetadata,
                 upload: {
                     ...result,
                     file,
@@ -827,17 +841,21 @@ export async function uploadPuts(opts) {
         }
     });
     const uploads = [];
+    const sentMetadata = [];
     const failures = [];
     let firstError;
     for (const slot of slots) {
-        if (slot.ok)
+        // Pushed together so the two arrays stay index-aligned across failures.
+        if (slot.ok) {
             uploads.push(slot.upload);
+            sentMetadata.push(slot.sentMetadata);
+        }
         else {
             firstError ??= slot.err;
             failures.push({ file: slot.file, error: errorDetail(slot.err) });
         }
     }
-    return { uploads, failures, firstError };
+    return { uploads, failures, firstError, sentMetadata };
 }
 /**
  * Best-effort call to `POST /v1/:workspace/github/promote` (server contract,
@@ -931,7 +949,7 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
         const n = parsed.positionals.length;
         process.stderr.write(`>> uploading ${n} file${n === 1 ? "" : "s"}\n`);
     }
-    const { uploads, failures, firstError } = await uploadAttachments({
+    const { uploads, failures, firstError, sentMetadata } = await uploadAttachments({
         client: ctx.client,
         target,
         files: parsed.positionals,
@@ -979,7 +997,7 @@ export async function runAttach(ctx, args, help = false, run = execRunner) {
         }
     }
     // Lever 3 (issue #469): tip when an image lands here with no `path` meta.
-    const pathHint = uploads.length > 0 && !ctx.quiet ? pathMetaHintFor(uploads) : undefined;
+    const pathHint = uploads.length > 0 && !ctx.quiet ? pathMetaHintFor(uploads, sentMetadata) : undefined;
     if (ctx.json) {
         await writeJson({
             target,
@@ -1672,7 +1690,7 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
         if (attachedRef)
             process.stderr.write(`>> attached to ${attachedRef}\n`);
     }
-    const { uploads, failures, firstError } = await uploadPuts({
+    const { uploads, failures, firstError, sentMetadata } = await uploadPuts({
         client: ctx.client,
         files,
         nameOverride: nameFlag,
@@ -1707,7 +1725,9 @@ export async function runPut(ctx, args, help = false, run = execRunner) {
     // `path` meta. Only relevant on the ghTarget path — the bare-put paths
     // above (staging/auto/dated) aren't attached to a PR/issue yet, so there's
     // nothing to look up from a page later.
-    const pathHint = ghTarget && uploads.length > 0 && !ctx.quiet ? pathMetaHintFor(uploads) : undefined;
+    const pathHint = ghTarget && uploads.length > 0 && !ctx.quiet
+        ? pathMetaHintFor(uploads, sentMetadata)
+        : undefined;
     // One JSON `hint` slot, shared with the #393 nudge (mutually exclusive with
     // it — nudge is undefined whenever staging took over). When staging fires,
     // prefer the more actionable binding warning over the generic staging note

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.29.0",
+  "version": "0.30.0",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,