@stacksjs/browser-extension 0.70.246 → 0.70.247

package/dist/firefox-previews.d.ts

@@ -0,0 +1,61 @@
+import type { ExtensionConfig } from './types';
+/**
+ * Pixel dimensions of a PNG or JPEG, read from its header.
+ *
+ * Enough to answer "does the listing already show these images", which is the
+ * only reason this file needs to know. Decoding them properly would mean
+ * making the whole codec stack a dependency of the publisher, to compare two
+ * pairs of integers.
+ */
+export declare function imageSize(bytes: Uint8Array): { width: number, height: number } | undefined;
+/**
+ * A short-lived HS256 token, which is what AMO's external API takes.
+ *
+ * Signed here rather than pulled from a JWT library: the payload is four
+ * claims and the signature is one HMAC, and `web-ext` — the only other AMO
+ * caller in this package — does not expose its own.
+ */
+export declare function amoToken(issuer: string, secret: string, now?: number): string;
+/** Read the previews a listing currently shows. */
+export declare function listFirefoxPreviews(addonId: string, token: string): Promise<FirefoxPreview[]>;
+/**
+ * Bring the listing's screenshots in line with the config.
+ *
+ * Skips the whole exchange when the listing already shows the same images at
+ * the same sizes in the same order — a publish should not churn a public
+ * listing's preview ids just because it ran again.
+ */
+export declare function syncFirefoxPreviews(config: ExtensionConfig, options?: FirefoxPreviewSyncOptions): Promise<FirefoxPreviewSyncResult>;
+/**
+ * Listing screenshots on addons.mozilla.org.
+ *
+ * Of the three stores this package publishes to, AMO is the middle case:
+ * Apple's API takes screenshots as part of a version's metadata, Chrome's has
+ * no endpoint for them at all, and AMO has a writable previews collection that
+ * nothing was using. So a Firefox listing kept whatever was dragged into the
+ * Developer Hub the first time — for very-good-adblock, two images at mismatched
+ * sizes and captions that said "A screenshot showcasing the extension" — while
+ * every other surface regenerated from the product.
+ *
+ * Replacement is upload-then-delete rather than delete-then-upload. Either
+ * order is fine when it works; only one of them leaves a public listing with no
+ * screenshots at all if the process dies in the middle.
+ */
+export declare interface FirefoxPreviewAuth {
+  issuer?: string
+  secret?: string
+}
+export declare interface FirefoxPreviewSyncOptions extends FirefoxPreviewAuth {
+  cwd?: string
+  dryRun?: boolean
+}
+export declare interface FirefoxPreview {
+  id: number
+  position: number
+  size: [number, number]
+}
+export declare interface FirefoxPreviewSyncResult {
+  unchanged: boolean
+  uploaded: FirefoxPreview[]
+  removed: number[]
+}

package/dist/firefox-previews.js

@@ -0,0 +1,100 @@
+import { createHmac, randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { basename, isAbsolute, resolve } from "node:path";
+import process from "node:process";
+const AMO_API = "https://addons.mozilla.org/api/v5";
+export function imageSize(bytes) {
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (bytes.length > 24 && view.getUint32(0) === 2303741511)
+    return { width: view.getUint32(16), height: view.getUint32(20) };
+  if (bytes.length > 4 && view.getUint16(0) === 65496) {
+    let offset = 2;
+    while (offset + 9 < bytes.length) {
+      if (view.getUint8(offset) !== 255) {
+        offset++;
+        continue;
+      }
+      const marker = view.getUint8(offset + 1);
+      if (marker >= 192 && marker <= 207 && marker !== 196 && marker !== 200 && marker !== 204)
+        return { height: view.getUint16(offset + 5), width: view.getUint16(offset + 7) };
+      offset += 2 + view.getUint16(offset + 2);
+    }
+  }
+  return;
+}
+export function amoToken(issuer, secret, now = Date.now()) {
+  const base64url = (value) => Buffer.from(value).toString("base64url"), issuedAt = Math.floor(now / 1000), header = base64url(JSON.stringify({ alg: "HS256", typ: "JWT" })), payload = base64url(JSON.stringify({
+    iss: issuer,
+    jti: randomUUID(),
+    iat: issuedAt,
+    exp: issuedAt + 240
+  })), signature = createHmac("sha256", secret).update(`${header}.${payload}`).digest("base64url");
+  return `${header}.${payload}.${signature}`;
+}
+function resolveAuth(options) {
+  const issuer = options.issuer ?? process.env.AMO_JWT_ISSUER ?? process.env.WEB_EXT_API_KEY, secret = options.secret ?? process.env.AMO_JWT_SECRET ?? process.env.WEB_EXT_API_SECRET, missing = [!issuer && "AMO_JWT_ISSUER", !secret && "AMO_JWT_SECRET"].filter(Boolean);
+  if (missing.length)
+    throw Error(`[browser-extension] missing Firefox Add-ons credentials: ${missing.join(", ")}`);
+  return { issuer, secret };
+}
+async function amo(path, token, init = {}) {
+  const response = await fetch(`${AMO_API}${path}`, {
+    ...init,
+    headers: { Authorization: `JWT ${token}`, ...init.headers }
+  });
+  if (!response.ok && response.status !== 404) {
+    const detail = await response.text().catch(() => "");
+    throw Error(`[browser-extension] AMO ${init.method ?? "GET"} ${path} failed (${response.status})${detail ? `: ${detail.slice(0, 300)}` : ""}`);
+  }
+  return response;
+}
+export async function listFirefoxPreviews(addonId, token) {
+  const response = await amo(`/addons/addon/${encodeURIComponent(addonId)}/`, token);
+  if (response.status === 404)
+    return [];
+  return ((await response.json()).previews ?? []).map((preview, index) => ({
+    id: preview.id,
+    position: preview.position ?? index,
+    size: preview.image_size ?? [0, 0]
+  }));
+}
+export async function syncFirefoxPreviews(config, options = {}) {
+  const store = config.firefoxAddons ?? {}, screenshots = store.screenshots ?? [];
+  if (!screenshots.length)
+    return { unchanged: !0, uploaded: [], removed: [] };
+  if (!config.geckoId)
+    throw Error("[browser-extension] Firefox previews need geckoId in config/extension.ts");
+  const cwd = options.cwd ?? process.cwd(), files = await Promise.all(screenshots.map(async (path) => {
+    const file = isAbsolute(path) ? path : resolve(cwd, path), bytes = new Uint8Array(await readFile(file).catch(() => {
+      throw Error(`[browser-extension] Firefox screenshot not found: ${path}`);
+    })), size = imageSize(bytes);
+    return { path: file, bytes, width: size?.width ?? 0, height: size?.height ?? 0 };
+  })), { issuer, secret } = resolveAuth(options), existing = await listFirefoxPreviews(config.geckoId, amoToken(issuer, secret));
+  if (files.every((file) => file.width > 0 && file.height > 0) && existing.length === files.length && existing.slice().sort((a, b) => a.position - b.position).every((preview, index) => preview.size[0] === files[index].width && preview.size[1] === files[index].height))
+    return { unchanged: !0, uploaded: [], removed: [] };
+  if (options.dryRun)
+    return { unchanged: !1, uploaded: [], removed: existing.map((preview) => preview.id) };
+  const uploaded = [];
+  for (const [index, file] of files.entries()) {
+    const form = new FormData;
+    form.append("image", new Blob([file.bytes], { type: "image/png" }), basename(file.path));
+    form.append("position", String(index));
+    const created = await (await amo(`/addons/addon/${encodeURIComponent(config.geckoId)}/previews/`, amoToken(issuer, secret), {
+      method: "POST",
+      body: form
+    })).json(), caption = store.screenshotCaptions?.[index];
+    if (caption)
+      await amo(`/addons/addon/${encodeURIComponent(config.geckoId)}/previews/${created.id}/`, amoToken(issuer, secret), {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ caption: { "en-US": caption } })
+      });
+    uploaded.push({ id: created.id, position: index, size: [file.width, file.height] });
+  }
+  const removed = [];
+  for (const preview of existing) {
+    await amo(`/addons/addon/${encodeURIComponent(config.geckoId)}/previews/${preview.id}/`, amoToken(issuer, secret), { method: "DELETE" });
+    removed.push(preview.id);
+  }
+  return { unchanged: !1, uploaded, removed };
+}

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export * from './app-store-submission';
 export * from './chrome-web-store';
 export * from './config';
 export * from './firefox-addons';
+export * from './firefox-previews';
 export * from './manifest';
 export * from './package';
 export * from './safari';

package/dist/index.js

@@ -4,6 +4,7 @@ export * from "./app-store-submission";
 export * from "./chrome-web-store";
 export * from "./config";
 export * from "./firefox-addons";
+export * from "./firefox-previews";
 export * from "./manifest";
 export * from "./package";
 export * from "./safari";

package/dist/types.d.ts

@@ -67,6 +67,8 @@ export declare interface FirefoxAddonsConfig {
   supportEmail?: string
   requiresPayment?: boolean
   artifactsDir?: string
+  screenshots?: string[]
+  screenshotCaptions?: string[]
 }
 export declare interface SafariAppStoreReviewContact {
   firstName: string

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/browser-extension",
   "type": "module",
-  "version": "0.70.246",
+  "version": "0.70.247",
   "description": "Build MV3 browser extensions (Chrome, Firefox, Safari) the Stacks way — manifest, content/background scripts, DNR rules, packaging, Safari container app, all config-driven.",
   "author": "Chris Breuer",
   "contributors": [