releasing

name

releasing

description

Ship this extension — cut a release and publish to the Chrome Web Store, Microsoft Edge Add-ons, and Firefox Add-ons (AMO) — and reason about its permissions and privacy posture. Use when bumping the version, packaging store zips, updating listing/store metadata, tagging a release, working on the tag-triggered release.yml workflow, debugging a Chrome Web Store API publish failure (unauthorized_client, invalid_grant, publisherId, Unauthorized), editing manifest permissions, adding an API that needs a new permission, writing store justifications, or answering "what data does it collect / is this private". Covers the OAuth/credential setup the CWS publish needs.

Releasing & publishing

One version bump propagates everywhere: WXT writes package.json's version into every browser's manifest.

Steps

1. Update CHANGELOG.md (move [Unreleased] items under the new version).
2. Bump version in package.json (semver).
3. Package all stores:

   corepack yarn zip:all
   

   Produces in apps/extension/.output/:
   • media-bulk-downloads-<version>-chrome.zip
   • media-bulk-downloads-<version>-edge.zip
   • media-bulk-downloads-<version>-firefox.zip + -sources.zip
4. Validate the Firefox build: corepack yarn lint:firefox (web-ext, expect 0 errors).
5. Upload:
   • Chrome Web Store → Developer Dashboard, the -chrome.zip.
   • Edge Add-ons → Partner Center, the -edge.zip (same Chromium package family; the CWS copy/justifications apply).
   • Firefox (AMO) → addons.mozilla.org/developers, the -firefox.zip plus the -sources.zip when prompted (AMO requires source for bundled add-ons).
6. Tag the release: git tag -a vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z. The tag must equal package.json's version (release.yml enforces this).

Convention here: bump version + CHANGELOG on a branch → PR → merge to main → tag the merge commit. Manual store uploads (step 5) are still done by hand except Chrome, which the tag can auto-publish (below).

Store status: Chrome / Firefox (AMO) / Edge are live; Opera and Safari are submitted, under review.

Safari (Mac App Store) — separate flow

Safari is not in zip:all/build:all. It ships as a native macOS app wrapping the extension, built on macOS only:

corepack yarn build:safari        # → apps/extension/.output/safari-mv3
./apps/safari-native/convert.sh   # safari-web-extension-converter → Xcode project

Then sign + submit through Xcode / App Store Connect (needs an Apple Developer account). The Safari manifest drops downloads/offscreen + optional notifications/DNR; the @mbd/platform seam supplies the fallbacks, and MAIN-world sniffers are inert (DOM-only collection). Full runbook + caveats: docs/store-submissions/SAFARI_APPSTORE.md, apps/safari-native/README.md.

Automated release (.github/workflows/release.yml)

Pushing a vX.Y.Z tag runs three jobs:

• validate — lint / type-check / test.
• release — yarn zip:all, then a GitHub Release with all four zips attached and the matching ## [X.Y.Z] CHANGELOG section as the body.
• publish-chrome — pushes the Chrome zip to the Web Store via Google's official REST API with plain curl (no npm package — the chrome-webstore-upload-cli path broke, see below). workflow_dispatch re-runs publish-chrome against the current package.json version without a new tag: gh workflow run release.yml --ref <branch>.

The GitHub Release always works; the Chrome publish depends on credentials being right (below). Edge/Firefox/Opera stay manual — grab their zips from the Release.

Chrome Web Store API publishing

publish-chrome calls the CWS API directly with curl — the v1.1 item-scoped endpoint (needs only CHROME_EXTENSION_ID, no publisher id): OAuth token → PUT upload → POST publish. Four secrets, all a matched set from one "Web application" OAuth client: CHROME_CLIENT_ID, CHROME_CLIENT_SECRET, CHROME_REFRESH_TOKEN, CHROME_EXTENSION_ID.

Full setup — minting the refresh token step by step, the v1.1-vs-v2 rationale, and the invalid_grant / unauthorized_client / Unauthorized / publisherId error catalog — is in references/chrome-webstore-api.md. Re-publish the current version without a new tag: gh workflow run release.yml --ref <branch>.

Permissions & privacy (keep in sync with the store justifications)

Declared in apps/extension/wxt.config.ts (manifest function). Keep this list and docs/store-submissions/CHROME_WEBSTORE.md §4 in sync.

Permission	Why
downloads	Save selected media via chrome.downloads.download
downloads.open	Open a downloaded file from in-app history (chrome.downloads.open)
storage	Settings (storage.sync) + history (storage.local), on-device
tabs	Read active tab URL/title to label downloads and open a source URL
contextMenus	Right-click actions (download all / this image, favourites)
offscreen	Assemble HLS/DASH streams in an offscreen document
host <all_urls>	Read media on any page; opt-in original-resolution fetches to media CDNs

Optional (requested at runtime when the feature enables, never at install):

Permission	Why
notifications	Desktop toast when a batch finishes (Settings → Downloads)
declarativeNetRequestWithHostAccess	"Retry w/ referer" on a hotlink-403: a short-lived single-URL session rule sets the source page as Referer/Origin, torn down immediately. Must be this variant — Chrome drops plain declarativeNetRequest from optional_permissions.

Before adding a permission: can an existing one do it? (activeTab vs <all_urls> — but this extension genuinely needs all-URLs for the badge + on-any-page collection.) Adding one (esp. downloads.open) triggers a re-permission prompt on update and needs a store justification — add both. Firefox MV3 also needs browser_specific_settings.gecko.data_collection_permissions (this extension declares ['none']).

Privacy stance (must stay true):

• Network-free by default — collection only reads what the page already loaded. The one opt-in exception (resolveOriginals) fetches higher-res originals directly from the media's own CDN, host-pinned, only while downloading.
• No servers, no analytics, no accounts. Settings/history never leave the device (sync settings stay in the user's own Chrome sync). The durable IndexedDB mirror of history/favourites/excluded/queue (via navigator.storage.persist()) is on-device and needs no manifest permission.
• Scheme allowlist: only http(s) (and data:image) is surfaced; page-supplied ids are shape-validated before URL interpolation, API-JSON URLs pinned to https + expected host. PRIVACY.md is the published policy — update it if data handling ever changes.

Store listing assets & copy

The full submission package — paste-ready name/summary/description, category, per-permission justifications, privacy/data disclosures, screenshot specs — lives in docs/store-submissions/CHROME_WEBSTORE.md (and the per-store siblings EDGE_ADDONS.md, FIREFOX_AMO.md, OPERA_ADDONS.md, SAFARI_APPSTORE.md). Privacy policy: PRIVACY.md (hosted at the repo's public URL). Screenshots: seven 1280×800 24-bit PNGs (no alpha) — assets/v2/screenshot-1-…-1280x800.png through -7-…; Opera also wants assets/v2/opera-promo-300x188.png. Other Chromium browsers (Brave/Opera/Vivaldi) use the Chrome zip.

Official store install badges

Use each store's official "install" badge (not third-party/shields), resized only — no recolor/border/radius — and always linking to our real listing. The assets are vendored so they never hotlink-break: assets/badges/ (root README) and docs/website/public/badges/ (docs site landing).

Store	Badge	Official source
Chrome Web Store	"Available in the Chrome Web Store" (chrome-web-store.png, with-border)	https://developer.chrome.com/docs/webstore/branding
Firefox (AMO)	"Get the Add-on" (firefox-get-the-addon.png)	https://blog.mozilla.org/addons/2015/11/10/promote-your-add-ons-with-the-get-the-add-on-button/
Microsoft	"Get it from Microsoft" (get-it-from-microsoft.svg)	https://get.microsoft.com/images/en-us%20{dark,light}.svg

Edge caveat: the extension ships on Edge Add-ons (microsoftedge.microsoft.com), which has no apps.microsoft.com listing and no dedicated badge program. The "Get it from Microsoft" badge is Microsoft-official but nominally a Microsoft-Store badge — we point it at the Edge Add-ons listing. Don't reuse a random apps.microsoft.com/badge/<id> id (the one first referenced, 9nksqgp7f2nh, is WhatsApp's). If a real Microsoft-Store listing ever exists, repoint it and swap in the id-specific badge. To refresh an asset, re-download from the source above into both badge dirs (keep the same filename).

References

• Submission packages (this repo) — docs/store-submissions/{CHROME_WEBSTORE,EDGE_ADDONS,FIREFOX_AMO,OPERA_ADDONS,SAFARI_APPSTORE}.md, PRIVACY.md, SECURITY.md, CHANGELOG.md
• Safari wrapper (this repo) — apps/safari-native/README.md, apps/safari-native/convert.sh
• Release workflow (this repo) — .github/workflows/release.yml; manifest source apps/extension/wxt.config.ts
• CWS API deep-dive (this skill) — references/chrome-webstore-api.md (OAuth setup, token minting, error catalog)

Further reading (external, optional — not required; the CWS specifics are captured in the ref above):

• WXT publishing / zip — https://wxt.dev/guide/essentials/publishing
• Chrome Web Store publishing — https://developer.chrome.com/docs/webstore/publish
• Chrome Web Store API (endpoints + OAuth) — https://developer.chrome.com/docs/webstore/using-api
• Google OAuth Playground (mint the refresh token) — https://developers.google.com/oauthplayground/
• Edge Add-ons submission — https://learn.microsoft.com/en-us/microsoft-edge/extensions-chromium/publish/publish-extension
• Firefox AMO submission — https://extensionworkshop.com/documentation/publish/submitting-an-add-on/
• Safari web extensions (convert + distribute) — https://developer.apple.com/documentation/safariservices/safari-web-extensions · App Store Connect — https://developer.apple.com/help/app-store-connect/
• Semantic Versioning — https://semver.org/
• Permissions — declare https://developer.chrome.com/docs/extensions/develop/concepts/declare-permissions · list https://developer.chrome.com/docs/extensions/reference/permissions-list · CWS user-data policy https://developer.chrome.com/docs/webstore/program-policies/user-data-faq · Firefox data-collection permissions https://extensionworkshop.com/documentation/develop/data-collection-permissions/