@stacksjs/browser-extension 0.70.120 → 0.70.122

package/README.md

@@ -17,6 +17,52 @@ buddy extension:build --target safari   # → dist-safari/ (browser.* namespace,
 buddy extension:package       # build + zip store-ready archives
 ```
 
+## Store publishing
+
+Stacks owns the store-specific upload clients as well as the builds. Chrome
+uses Web Store API v2 with a service account; Firefox uses Mozilla's official
+`web-ext` client and AMO v5 API; Safari uses App Store Connect and Xcode.
+
+```sh
+buddy extension:chrome:status
+buddy extension:chrome:publish          # build, zip, upload, submit for review
+buddy extension:chrome:publish --upload-only
+buddy extension:firefox:publish         # build, submit, sign through AMO
+buddy extension:safari:provision        # register Bundle IDs + check app record
+buddy extension:safari:publish
+```
+
+Chrome reads `CHROME_WEB_STORE_SERVICE_ACCOUNT_PATH` (or
+`GOOGLE_APPLICATION_CREDENTIALS`) and the configured
+`chromeWebStore.publisherId`/`itemId`. The API only updates existing items, so
+create the initial Developer Dashboard item once and link the service-account
+email to the publisher account. Firefox reads `AMO_JWT_ISSUER` and
+`AMO_JWT_SECRET`; `web-ext` can create the initial listing when
+`firefoxAddons.license` and `firefoxAddons.categories` are configured.
+
+For tag-driven publication, call Stacks' reusable workflow from the extension
+repository instead of duplicating store orchestration:
+
+```yaml
+jobs:
+  publish:
+    uses: stacksjs/stacks/.github/workflows/browser-extension-release.yml@v0.70.122
+    with:
+      chrome-publisher-id: ${{ vars.CHROME_WEB_STORE_PUBLISHER_ID }}
+      safari-enabled: ${{ vars.ENABLE_SAFARI_PUBLISH == 'true' }}
+    secrets:
+      CHROME_WEB_STORE_SERVICE_ACCOUNT_JSON: ${{ secrets.CHROME_WEB_STORE_SERVICE_ACCOUNT_JSON }}
+      AMO_JWT_ISSUER: ${{ secrets.AMO_JWT_ISSUER }}
+      AMO_JWT_SECRET: ${{ secrets.AMO_JWT_SECRET }}
+      APP_STORE_CONNECT_API_KEY: ${{ secrets.APP_STORE_CONNECT_API_KEY }}
+      APP_STORE_CONNECT_API_KEY_ID: ${{ secrets.APP_STORE_CONNECT_API_KEY_ID }}
+      APP_STORE_CONNECT_API_ISSUER_ID: ${{ secrets.APP_STORE_CONNECT_API_ISSUER_ID }}
+```
+
+It packages every configured target, publishes Chrome and Firefox in
+independent jobs, optionally uploads Safari with stable Xcode, and creates the
+GitHub Release only after the enabled stores succeed.
+
 ## Safari
 
 Safari Web Extensions ship inside a macOS app, so the safari target has two
@@ -54,6 +100,8 @@ export default defineExtension({
   name: 'My Extension',
   description: 'Does something useful.',
   geckoId: 'my-ext@example.com',      // required to ship on Firefox
+  chromeWebStore: { publisherId: 'publisher-id', itemId: 'extension-id' },
+  firefoxAddons: { license: 'MIT', categories: ['privacy-security'] },
   safariBundleId: 'com.example.MyExtension', // Safari container app bundle id
   targets: ['chrome', 'firefox'],
 
@@ -109,6 +157,8 @@ import {
   buildExtension,
   buildAllTargets,
   packageExtension,
+  publishChromeExtension,
+  publishFirefoxExtension,
   generateManifest,
   rewriteBrowserNamespace,
   scaffoldSafariApp,

package/dist/chrome-web-store.d.ts

@@ -0,0 +1,55 @@
+import type { ChromeWebStoreConfig, ExtensionConfig } from './types';
+/** Build the RS256 assertion Google exchanges for a short-lived OAuth token. */
+export declare function chromeWebStoreServiceAccountAssertion(serviceAccount: GoogleServiceAccount, now?: unknown): string;
+/** Build, package, upload, and optionally submit an existing Chrome Web Store item. */
+export declare function publishChromeExtension(config: ExtensionConfig, options: ChromeWebStorePublishOptions): Promise<{ packagePath: string, upload: ChromeUploadResult, publish?: ChromePublishResult }>;
+export declare interface GoogleServiceAccount {
+  client_email: string
+  private_key: string
+  token_uri?: string
+}
+export declare interface ChromeWebStoreAuth {
+  accessToken?: string
+  serviceAccountPath?: string
+}
+export declare interface ChromeWebStoreClientOptions extends ChromeWebStoreAuth {
+  baseUrl?: string
+  fetch?: typeof globalThis.fetch
+  now?: () => number
+  wait?: (milliseconds: number) => Promise<void>
+}
+export declare interface ChromeWebStoreStatus {
+  name: string
+  itemId: string
+  lastAsyncUploadState?: 'UPLOAD_STATE_UNSPECIFIED' | 'SUCCEEDED' | 'IN_PROGRESS' | 'FAILED' | 'NOT_FOUND'
+  publishedItemRevisionStatus?: { state: string, distributionChannels?: Array<{ deployPercentage: number, crxVersion: string }> }
+  submittedItemRevisionStatus?: { state: string, distributionChannels?: Array<{ deployPercentage: number, crxVersion: string }> }
+  takenDown?: boolean
+  warned?: boolean
+}
+export declare interface ChromeUploadResult {
+  name: string
+  itemId: string
+  crxVersion?: string
+  uploadState: 'UPLOAD_STATE_UNSPECIFIED' | 'SUCCEEDED' | 'IN_PROGRESS' | 'FAILED' | 'NOT_FOUND'
+}
+export declare interface ChromePublishResult {
+  name: string
+  itemId: string
+  state: string
+  warningInfo?: { warnings?: Array<{ reason: string, description: string }> }
+}
+export declare interface ChromeWebStorePublishOptions extends ChromeWebStoreClientOptions {
+  version: string
+  cwd?: string
+  packagePath?: string
+  uploadOnly?: boolean
+  blockOnWarnings?: boolean
+}
+export declare class ChromeWebStoreClient {
+  constructor(options?: ChromeWebStoreClientOptions);
+  fetchStatus(config: ChromeWebStoreConfig): Promise<ChromeWebStoreStatus>;
+  upload(config: ChromeWebStoreConfig, packagePath: string): Promise<ChromeUploadResult>;
+  publish(config: ChromeWebStoreConfig, options?: { blockOnWarnings?: boolean }): Promise<ChromePublishResult>;
+  waitForUpload(config: ChromeWebStoreConfig, maxAttempts?: number): Promise<ChromeWebStoreStatus>;
+}

package/dist/chrome-web-store.js

@@ -0,0 +1,137 @@
+import { createPrivateKey, sign } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { packageExtension } from "./package";
+const chromeWebStoreScope = "https://www.googleapis.com/auth/chromewebstore", chromeWebStoreBaseUrl = "https://chromewebstore.googleapis.com";
+function base64urlJson(value) {
+  return Buffer.from(JSON.stringify(value)).toString("base64url");
+}
+export function chromeWebStoreServiceAccountAssertion(serviceAccount, now = Math.floor(Date.now() / 1000)) {
+  const tokenUri = serviceAccount.token_uri ?? "https://oauth2.googleapis.com/token", input = `${base64urlJson({ alg: "RS256", typ: "JWT" })}.${base64urlJson({
+    iss: serviceAccount.client_email,
+    scope: chromeWebStoreScope,
+    aud: tokenUri,
+    iat: now,
+    exp: now + 3600
+  })}`;
+  let key;
+  try {
+    key = createPrivateKey(serviceAccount.private_key);
+  } catch (error) {
+    throw Error(`[browser-extension] Chrome Web Store service-account key could not be parsed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return `${input}.${sign("sha256", Buffer.from(input), key).toString("base64url")}`;
+}
+async function resolveChromeAccessToken(options) {
+  const supplied = options.accessToken ?? process.env.CHROME_WEB_STORE_ACCESS_TOKEN;
+  if (supplied)
+    return supplied;
+  const configuredPath = options.serviceAccountPath ?? process.env.CHROME_WEB_STORE_SERVICE_ACCOUNT_PATH ?? process.env.GOOGLE_APPLICATION_CREDENTIALS;
+  if (!configuredPath)
+    throw Error("[browser-extension] missing Chrome Web Store credentials: CHROME_WEB_STORE_SERVICE_ACCOUNT_PATH or CHROME_WEB_STORE_ACCESS_TOKEN");
+  const keyPath = resolve(configuredPath);
+  if (!existsSync(keyPath))
+    throw Error(`[browser-extension] Chrome Web Store service-account key not found: ${keyPath}`);
+  let serviceAccount;
+  try {
+    serviceAccount = JSON.parse(readFileSync(keyPath, "utf8"));
+  } catch (error) {
+    throw Error(`[browser-extension] Chrome Web Store service-account JSON could not be parsed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!serviceAccount.client_email || !serviceAccount.private_key)
+    throw Error("[browser-extension] Chrome Web Store service-account JSON needs client_email and private_key");
+  const tokenUri = serviceAccount.token_uri ?? "https://oauth2.googleapis.com/token", response = await (options.fetch ?? globalThis.fetch)(tokenUri, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+      assertion: chromeWebStoreServiceAccountAssertion(serviceAccount, options.now?.())
+    })
+  }), body = await response.json().catch(() => ({}));
+  if (!response.ok || !body.access_token)
+    throw Error(`[browser-extension] Google OAuth token exchange failed (${response.status})${body.error_description ? `: ${body.error_description}` : ""}`);
+  return body.access_token;
+}
+function storeItemName(config) {
+  return `publishers/${encodeURIComponent(config.publisherId)}/items/${encodeURIComponent(config.itemId)}`;
+}
+
+export class ChromeWebStoreClient {
+  options;
+  baseUrl;
+  accessToken;
+  constructor(options = {}) {
+    this.options = options;
+    this.baseUrl = (options.baseUrl ?? chromeWebStoreBaseUrl).replace(/\/$/, "");
+  }
+  async request(path, init = {}) {
+    this.accessToken ??= resolveChromeAccessToken(this.options);
+    const response = await (this.options.fetch ?? globalThis.fetch)(`${this.baseUrl}${path}`, {
+      ...init,
+      headers: {
+        Authorization: `Bearer ${await this.accessToken}`,
+        ...init.headers
+      }
+    });
+    if (!response.ok) {
+      const body = await response.json().catch(() => ({})), detail = body.error?.message ?? body.message;
+      throw Error(`[browser-extension] Chrome Web Store ${init.method ?? "GET"} ${path} failed (${response.status})${detail ? `: ${detail}` : ""}`);
+    }
+    return await response.json();
+  }
+  fetchStatus(config) {
+    return this.request(`/v2/${storeItemName(config)}:fetchStatus`);
+  }
+  async upload(config, packagePath) {
+    const file = Bun.file(resolve(packagePath));
+    if (!await file.exists())
+      throw Error(`[browser-extension] Chrome package not found: ${resolve(packagePath)}`);
+    return await this.request(`/upload/v2/${storeItemName(config)}:upload`, {
+      method: "POST",
+      headers: { "Content-Type": "application/zip" },
+      body: new Uint8Array(await file.arrayBuffer())
+    });
+  }
+  publish(config, options = {}) {
+    if (config.deployPercentage !== void 0 && (!Number.isInteger(config.deployPercentage) || config.deployPercentage < 0 || config.deployPercentage > 100))
+      throw Error("[browser-extension] chromeWebStore.deployPercentage must be an integer from 0 to 100");
+    const body = {
+      publishType: config.publishType ?? "DEFAULT_PUBLISH",
+      skipReview: config.skipReview ?? !1,
+      blockOnWarnings: options.blockOnWarnings ?? !0
+    };
+    if (config.deployPercentage !== void 0)
+      body.deployInfos = [{ deployPercentage: config.deployPercentage }];
+    return this.request(`/v2/${storeItemName(config)}:publish`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body)
+    });
+  }
+  async waitForUpload(config, maxAttempts = 30) {
+    for (let attempt = 0;attempt < maxAttempts; attempt += 1) {
+      const status = await this.fetchStatus(config);
+      if (status.lastAsyncUploadState !== "IN_PROGRESS") {
+        if (status.lastAsyncUploadState === "FAILED")
+          throw Error("[browser-extension] Chrome Web Store package processing failed");
+        return status;
+      }
+      await (this.options.wait ?? ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds))))(2000);
+    }
+    throw Error("[browser-extension] Chrome Web Store package processing timed out");
+  }
+}
+export async function publishChromeExtension(config, options) {
+  if (!config.chromeWebStore)
+    throw Error("[browser-extension] Chrome publishing needs chromeWebStore.publisherId and chromeWebStore.itemId in config/extension.ts");
+  const cwd = options.cwd ?? process.cwd(), packagePath = options.packagePath ?? await packageExtension(config, { target: "chrome", version: options.version, cwd }), client = new ChromeWebStoreClient(options), upload = await client.upload(config.chromeWebStore, packagePath);
+  if (upload.uploadState === "IN_PROGRESS")
+    await client.waitForUpload(config.chromeWebStore);
+  else if (upload.uploadState !== "SUCCEEDED")
+    throw Error(`[browser-extension] Chrome Web Store upload failed with state ${upload.uploadState}`);
+  return {
+    packagePath,
+    upload,
+    publish: options.uploadOnly ? void 0 : await client.publish(config.chromeWebStore, { blockOnWarnings: options.blockOnWarnings })
+  };
+}

package/dist/firefox-addons.d.ts

@@ -0,0 +1,22 @@
+import type { ExtensionConfig, FirefoxAddonsConfig } from './types';
+/** Metadata accepted by AMO v5 when web-ext creates the first listed version. */
+export declare function firefoxListingMetadata(config: ExtensionConfig, store: FirefoxAddonsConfig): Record<string, unknown> | undefined;
+/** Build and submit a Firefox extension through Mozilla's official web-ext/AMO v5 flow. */
+export declare function publishFirefoxExtension(config: ExtensionConfig, options: FirefoxPublishOptions): Promise<FirefoxPublishResult>;
+export declare interface FirefoxAddonsAuth {
+  issuer?: string
+  secret?: string
+}
+export declare interface FirefoxPublishOptions extends FirefoxAddonsAuth {
+  version: string
+  cwd?: string
+  build?: boolean
+  sourceCodePath?: string
+  timeout?: number
+  approvalTimeout?: number
+}
+export declare interface FirefoxPublishResult {
+  artifactsDir: string
+  artifacts: string[]
+  channel: 'listed' | 'unlisted'
+}

package/dist/firefox-addons.js

@@ -0,0 +1,82 @@
+import { existsSync, readdirSync } from "node:fs";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { buildExtension, resolveOutdir } from "./build";
+function resolveFirefoxAuth(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 };
+}
+export function firefoxListingMetadata(config, store) {
+  if (!store.license && !store.categories?.length)
+    return;
+  if (!store.license || !store.categories?.length)
+    throw Error("[browser-extension] a new Firefox listing needs both firefoxAddons.license and firefoxAddons.categories");
+  return {
+    version: { license: store.license },
+    categories: { firefox: store.categories },
+    summary: { "en-US": config.description },
+    ...store.homepage ? { homepage: { "en-US": store.homepage } } : {},
+    ...store.supportEmail ? { support_email: { "en-US": store.supportEmail } } : {},
+    requires_payment: store.requiresPayment ?? !1
+  };
+}
+export async function publishFirefoxExtension(config, options) {
+  if (!config.geckoId)
+    throw Error("[browser-extension] Firefox publishing needs geckoId in config/extension.ts");
+  const store = config.firefoxAddons ?? {}, auth = resolveFirefoxAuth(options), cwd = options.cwd ?? process.cwd();
+  if (options.build !== !1)
+    await buildExtension(config, { target: "firefox", version: options.version, cwd });
+  const sourceDir = resolve(cwd, resolveOutdir(config, "firefox")), artifactsDir = resolve(cwd, store.artifactsDir ?? "web-ext-artifacts"), executable = Bun.which("web-ext");
+  if (!executable)
+    throw Error("[browser-extension] web-ext is unavailable; reinstall @stacksjs/browser-extension dependencies");
+  await mkdir(artifactsDir, { recursive: !0 });
+  const before = new Set(existsSync(artifactsDir) ? readdirSync(artifactsDir) : []), tempDir = await mkdtemp(join(tmpdir(), "stacks-firefox-publish-"));
+  try {
+    const args = [
+      executable,
+      "sign",
+      "--source-dir",
+      sourceDir,
+      "--artifacts-dir",
+      artifactsDir,
+      "--channel",
+      store.channel ?? "listed",
+      "--timeout",
+      String(options.timeout ?? 300000),
+      "--approval-timeout",
+      String(options.approvalTimeout ?? 0),
+      "--no-input",
+      "--boring"
+    ], metadata = firefoxListingMetadata(config, store);
+    if (metadata) {
+      const metadataPath = join(tempDir, "amo-metadata.json");
+      await Bun.write(metadataPath, `${JSON.stringify(metadata, null, 2)}
+`);
+      args.push("--amo-metadata", metadataPath);
+    }
+    if (options.sourceCodePath)
+      args.push("--upload-source-code", resolve(cwd, options.sourceCodePath));
+    const exitCode = await Bun.spawn(args, {
+      cwd,
+      env: {
+        ...process.env,
+        WEB_EXT_API_KEY: auth.issuer,
+        WEB_EXT_API_SECRET: auth.secret
+      },
+      stdout: "inherit",
+      stderr: "inherit"
+    }).exited;
+    if (exitCode !== 0)
+      throw Error(`[browser-extension] Firefox Add-ons submission failed (${exitCode})`);
+  } finally {
+    await rm(tempDir, { recursive: !0, force: !0 });
+  }
+  return {
+    artifactsDir,
+    artifacts: readdirSync(artifactsDir).filter((file) => !before.has(file)),
+    channel: store.channel ?? "listed"
+  };
+}

package/dist/index.d.ts

@@ -9,7 +9,9 @@
  */
 export * from './build';
 export * from './app-store-connect';
+export * from './chrome-web-store';
 export * from './config';
+export * from './firefox-addons';
 export * from './manifest';
 export * from './package';
 export * from './safari';

package/dist/index.js

@@ -1,6 +1,8 @@
 export * from "./build";
 export * from "./app-store-connect";
+export * from "./chrome-web-store";
 export * from "./config";
+export * from "./firefox-addons";
 export * from "./manifest";
 export * from "./package";
 export * from "./safari";

package/dist/types.d.ts

@@ -52,10 +52,28 @@ export declare interface BuildContext {
   version: string
   cwd: string
 }
+export declare interface ChromeWebStoreConfig {
+  publisherId: string
+  itemId: string
+  publishType?: 'DEFAULT_PUBLISH' | 'STAGED_PUBLISH'
+  deployPercentage?: number
+  skipReview?: boolean
+}
+export declare interface FirefoxAddonsConfig {
+  channel?: 'listed' | 'unlisted'
+  license?: string
+  categories?: string[]
+  homepage?: string
+  supportEmail?: string
+  requiresPayment?: boolean
+  artifactsDir?: string
+}
 export declare interface ExtensionConfig {
   name: string
   description: string
   geckoId?: string
+  chromeWebStore?: ChromeWebStoreConfig
+  firefoxAddons?: FirefoxAddonsConfig
   safariBundleId?: string
   safariTeamId?: string
   safariExclude?: string[]

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stacksjs/browser-extension",
   "type": "module",
-  "version": "0.70.120",
+  "version": "0.70.122",
   "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": [
@@ -59,5 +59,8 @@
   },
   "devDependencies": {
     "better-dx": "^0.2.17"
+  },
+  "dependencies": {
+    "web-ext": "^10.5.0"
   }
 }