extension-from-store 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Cezar Augusto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+[npm-version-image]: https://img.shields.io/npm/v/extension-from-store.svg?color=0078D7
+[npm-version-url]: https://www.npmjs.com/package/extension-from-store
+[npm-downloads-image]: https://img.shields.io/npm/dm/extension-from-store.svg?color=2ecc40
+[npm-downloads-url]: https://www.npmjs.com/package/extension-from-store
+[action-image]: https://github.com/cezaraugusto/extension-from-store/actions/workflows/ci.yml/badge.svg?branch=main
+[action-url]: https://github.com/cezaraugusto/extension-from-store/actions
+
+> Download public browser extensions from official stores
+
+# extension-from-store [![Version][npm-version-image]][npm-version-url] [![Downloads][npm-downloads-image]][npm-downloads-url] [![workflow][action-image]][action-url]
+
+- Chrome Web Store, Microsoft Edge Add-ons, Firefox AMO
+- Easy-to-use API
+- Node.js + CLI support
+
+## Install
+
+```bash
+npm i extension-from-store
+```
+
+## Usage
+
+Designed for quiet reliability, extension-from-store keeps the interface simple and the output predictable.
+
+**Via Node.js:**
+
+```ts
+import {fetchExtensionFromStore} from 'extension-from-store'
+
+const url =
+  'https://chromewebstore.google.com/detail/adblock-plus-free-ad-bloc/cfhdojbkjhnklbpkdaibdccddilifddb'
+
+const options = {
+  outDir: './extensions',
+  userAgent: 'my-tool/1.0.0',
+  extract: true,
+  logger: {
+    onInfo: (message) => console.log(message),
+    onWarn: (message) => console.warn(message),
+    onError: (message, error) => console.error(message, error)
+  }
+}
+
+await fetchExtensionFromStore(url, options)
+```
+
+**Via CLI (default command is `fetch`):**
+
+```bash
+npx extension-from-store --url "<store-item-url>"
+npx extension-from-store --url "<store-item-url>" --out ./my-exts
+npx extension-from-store --url "<store-item-url>" --version 2.1.0 --extract
+npx extension-from-store --url "<store-item-url>" --extract
+```
+
+The store is detected from the URL.
+
+## Output
+
+```
+<out>/
+  <identifier>@<resolved-version>/
+    extension.meta.json
+    ...
+```
+
+If the target folder already exists, the operation fails.
+
+By default, extension-from-store downloads the archive without extraction. When you pass `--extract`, it unpacks the archive and writes metadata.
+
+When extraction is disabled, the archive is saved as:
+
+```
+<out>/<identifier>[@<version>].crx
+<out>/<identifier>[@<version>].xpi
+```
+
+## Extraction Rules
+
+- `.crx`: strip CRX header, extract ZIP payload
+- `.xpi`: treat as ZIP
+- No normalization, no rewriting, no formatting
+
+## `extension.meta.json`
+
+```json
+{
+  "store": "chrome | edge | firefox",
+  "identifier": "<identifier derived from the URL>",
+  "version": "<resolved version>",
+  "manifestVersion": 2 | 3
+}
+```
+
+This file is written by extension-from-store to the same folder as the extracted files.
+
+## CLI Flags
+
+| Flag | Required | Description |
+| --- | --- | --- |
+| `--url <string>` | Yes | Extension URL |
+| `--out <path>` | No | Output directory (default: `./extensions`) |
+| `--version <string>` | No | Version hint |
+| `--user-agent <string>` | No | Override user agent |
+| `--extract` | No | Extract after download (default: download only) |
+| `--quiet` | No | Suppress info logs |
+| `--verbose` | No | Emit verbose info logs |
+| `--json` | No | JSON lines output to stdout |
+
+
+## Logging
+
+Library logging is opt-in via the `logger` hooks. The library never writes directly to stdout/stderr.
+
+## Exit Codes
+
+- `0` success
+- `1` invalid input
+- `2` unsupported store
+- `3` not found / not public
+- `4` download failed
+- `5` extraction failed
+- `6` filesystem conflict
+- `7` store incompatibility
+
+## License
+
+MIT (c) Cezar Augusto.

package/bin.cjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+'use strict';
+
+const mod = require('./dist/index.cjs');
+const fetchExtensionFromStore = mod.fetchExtensionFromStore;
+const extensionFromStoreError = mod.extensionFromStoreError;
+
+const EXIT_CODES = {
+  InvalidInput: 1,
+  UnsupportedStore: 2,
+  NotFound: 3,
+  NotPublic: 3,
+  DownloadFailed: 4,
+  ExtractionFailed: 5,
+  FilesystemConflict: 6,
+  StoreIncompatibility: 7,
+};
+
+function parseArgs(argv) {
+  const args = [...argv];
+  if (args[0] === 'fetch') args.shift();
+
+  const result = {
+    url: '',
+    out: '',
+    version: '',
+    userAgent: '',
+    extract: false,
+    quiet: false,
+    verbose: false,
+    json: false,
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (arg === '--url') {
+      result.url = args[++i] || '';
+      continue;
+    }
+
+    if (arg === '--out') {
+      result.out = args[++i] || '';
+      continue;
+    }
+
+    if (arg === '--version') {
+      result.version = args[++i] || '';
+      continue;
+    }
+    if (arg === '--extract') {
+      result.extract = true;
+      continue;
+    }
+
+    if (arg === '--user-agent') {
+      result.userAgent = args[++i] || '';
+      continue;
+    }
+
+    if (arg === '--quiet') {
+      result.quiet = true;
+      continue;
+    }
+
+    if (arg === '--verbose') {
+      result.verbose = true;
+      continue;
+    }
+
+    if (arg === '--json') {
+      result.json = true;
+      continue;
+    }
+
+    throw new Error(`Unknown flag: ${arg}`);
+  }
+
+  if (!result.url) {
+    throw new Error('Missing required flag: --url');
+  }
+
+  return result;
+}
+
+function createCliLogger(opts) {
+  const emit = (level, message, error) => {
+    const payload = { level, message };
+
+    if (error) payload.error = String(error);
+
+    console.log(JSON.stringify(payload));
+  };
+
+  if (opts.json) {
+    return {
+      onInfo: (message) => emit('info', message),
+      onWarn: (message) => emit('warn', message),
+      onError: (message, error) => emit('error', message, error),
+    };
+  }
+
+  return {
+    onInfo: opts.quiet ? undefined : (message) => console.log(message),
+    onWarn: opts.quiet ? undefined : (message) => console.error(message),
+    onError: (message, error) => {
+      const text = error ? `${message}\n${String(error)}` : message;
+      console.error(text);
+    },
+  };
+}
+
+async function main() {
+  let args = null;
+
+  try {
+    args = parseArgs(process.argv.slice(2));
+    const logger = createCliLogger(args);
+    await fetchExtensionFromStore(
+      args.url,
+      {
+        outDir: args.out || undefined,
+        userAgent: args.userAgent || undefined,
+        version: args.version || undefined,
+        extract: args.extract,
+        logger,
+      },
+    );
+
+    process.exit(0);
+  } catch (error) {
+    if (error instanceof extensionFromStoreError) {
+      const code = EXIT_CODES[error.code] || 1;
+      const message = error.message || 'Extension fetch failed';
+
+      if (args?.json) {
+        console.log(JSON.stringify({ level: 'error', message }));
+      } else if (code !== 0) {
+        console.error(message);
+      }
+
+      process.exit(code);
+    }
+    const message = String(error?.message || error);
+
+    if (args?.json) {
+      console.log(JSON.stringify({ level: 'error', message }));
+    } else {
+      console.error(message);
+    }
+
+    process.exit(1);
+  }
+}
+
+main();

package/bin.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+
+const mod = require('./dist/index.cjs');
+const fetchExtensionFromStore = mod.fetchExtensionFromStore;
+const extensionFromStoreError = mod.extensionFromStoreError;
+
+const EXIT_CODES = {
+  InvalidInput: 1,
+  UnsupportedStore: 2,
+  NotFound: 3,
+  NotPublic: 3,
+  DownloadFailed: 4,
+  ExtractionFailed: 5,
+  FilesystemConflict: 6,
+  StoreIncompatibility: 7,
+};
+
+function parseArgs(argv) {
+  const args = [...argv];
+
+  if (args[0] === 'fetch') args.shift();
+
+  const result = {
+    url: '',
+    out: '',
+    version: '',
+    userAgent: '',
+    extract: false,
+    quiet: false,
+    verbose: false,
+    json: false,
+  };
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (arg === '--url') {
+      result.url = args[++i] || '';
+      continue;
+    }
+
+    if (arg === '--out') {
+      result.out = args[++i] || '';
+      continue;
+    }
+
+    if (arg === '--version') {
+      result.version = args[++i] || '';
+      continue;
+    }
+    if (arg === '--extract') {
+      result.extract = true;
+      continue;
+    }
+
+    if (arg === '--user-agent') {
+      result.userAgent = args[++i] || '';
+      continue;
+    }
+
+    if (arg === '--quiet') {
+      result.quiet = true;
+      continue;
+    }
+
+    if (arg === '--verbose') {
+      result.verbose = true;
+      continue;
+    }
+
+    if (arg === '--json') {
+      result.json = true;
+      continue;
+    }
+
+    throw new Error(`Unknown flag: ${arg}`);
+  }
+
+  if (!result.url) {
+    throw new Error('Missing required flag: --url');
+  }
+
+  return result;
+}
+
+function createCliLogger(opts) {
+  const emit = (level, message, error) => {
+    const payload = { level, message };
+    if (error) payload.error = String(error);
+    console.log(JSON.stringify(payload));
+  };
+
+  if (opts.json) {
+    return {
+      onInfo: (message) => emit('info', message),
+      onWarn: (message) => emit('warn', message),
+      onError: (message, error) => emit('error', message, error),
+    };
+  }
+
+  return {
+    onInfo: opts.quiet ? undefined : (message) => console.log(message),
+    onWarn: opts.quiet ? undefined : (message) => console.error(message),
+    onError: (message, error) => {
+      const text = error ? `${message}\n${String(error)}` : message;
+      console.error(text);
+    },
+  };
+}
+
+async function main() {
+  let args = null;
+
+  try {
+    args = parseArgs(process.argv.slice(2));
+    const logger = createCliLogger(args);
+    await fetchExtensionFromStore(
+      args.url,
+      {
+        outDir: args.out || undefined,
+        userAgent: args.userAgent || undefined,
+        version: args.version || undefined,
+        extract: args.extract,
+        logger,
+      },
+    );
+    process.exit(0);
+  } catch (error) {
+    if (error instanceof extensionFromStoreError) {
+      const code = EXIT_CODES[error.code] || 1;
+      const message = error.message || 'Extension fetch failed';
+
+      if (args?.json) {
+        console.log(JSON.stringify({ level: 'error', message }));
+      } else if (code !== 0) {
+        console.error(message);
+      }
+
+      process.exit(code);
+    }
+    const message = String(error?.message || error);
+
+    if (args?.json) {
+      console.log(JSON.stringify({ level: 'error', message }));
+    } else {
+      console.error(message);
+    }
+
+    process.exit(1);
+  }
+}
+
+main();

package/dist/errors.d.ts

@@ -0,0 +1,7 @@
+export type ErrorCode = 'InvalidInput' | 'UnsupportedStore' | 'NotFound' | 'NotPublic' | 'DownloadFailed' | 'ExtractionFailed' | 'FilesystemConflict' | 'StoreIncompatibility';
+export declare class extensionFromStoreError extends Error {
+    readonly code: ErrorCode;
+    readonly cause?: unknown;
+    constructor(code: ErrorCode, message: string, cause?: unknown);
+}
+export declare function asExtensionFromStoreError(error: unknown, fallback: extensionFromStoreError): extensionFromStoreError;

package/dist/extract.d.ts

@@ -0,0 +1,3 @@
+export declare function stripCrxHeader(buffer: Buffer): Buffer;
+export declare function extractCrx(crxPath: string, extractDir: string, workDir: string): Promise<void>;
+export declare function extractZipArchive(zipPath: string, extractDir: string): Promise<void>;

package/dist/http.d.ts

@@ -0,0 +1,10 @@
+import { type Logger } from './logger';
+type HttpOptions = {
+    userAgent?: string;
+    logger?: Logger;
+};
+export declare function resolveFinalUrl(url: string, options: HttpOptions, maxRedirects?: number): Promise<string>;
+export declare function downloadToFile(url: string, filePath: string, options: HttpOptions, maxRedirects?: number): Promise<void>;
+export declare function requestJson<T>(url: string, options: HttpOptions, maxRedirects?: number): Promise<T>;
+export declare function requestText(url: string, options: HttpOptions, maxRedirects?: number): Promise<string>;
+export {};