@swell/cli 2.7.1 → 2.9.0

package/dist/commands/app/dev.d.ts

@@ -8,6 +8,7 @@ export default class AppDev extends PushAppCommand {
         'no-push': import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
         port: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
         'frontend-port': import("@oclif/core/lib/interfaces/parser.js").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        function: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
         'storefront-id': import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
         'storefront-select': import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
         yes: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
@@ -17,6 +18,7 @@ export default class AppDev extends PushAppCommand {
     };
     static summary: string;
     functionErrors: Map<string, string>;
+    functionFilter: string | null;
     functionPorts: Map<string, number>;
     functionProcesses: Map<string, ChildProcess>;
     tmpDir: string;

package/dist/commands/app/dev.js

@@ -18,6 +18,7 @@ export default class AppDev extends PushAppCommand {
         'swell app dev --storefront-id <id>',
         'swell app dev --port 3000',
         'swell app dev --port 3000 --frontend-port 4000',
+        'swell app dev --function my-function',
     ];
     static flags = {
         'no-push': Flags.boolean({
@@ -30,6 +31,9 @@ export default class AppDev extends PushAppCommand {
         'frontend-port': Flags.integer({
             description: 'specify the port for the frontend dev server when running with frontend',
         }),
+        function: Flags.string({
+            description: 'run only the named function',
+        }),
         'storefront-id': Flags.string({
             description: 'for storefront apps, identify a storefront to preview and push theme files to',
         }),
@@ -48,6 +52,8 @@ export default class AppDev extends PushAppCommand {
     };
     static summary = `Run an app in dev mode from your local machine.`;
     functionErrors = new Map();
+    // When set, only this function name is bundled, started, and watched
+    functionFilter = null;
     // All available functions
     functionPorts = new Map();
     // Wrangler child processes to kill on cleanup
@@ -62,6 +68,7 @@ export default class AppDev extends PushAppCommand {
         const { flags } = await this.parse(AppDev);
         const { port, 'frontend-port': frontendPort } = flags;
         const noPush = flags['no-push'];
+        this.functionFilter = flags.function ?? null;
         if (!(await this.ensureAppExists(undefined, false))) {
             return;
         }
@@ -213,12 +220,18 @@ ENVIRONMENT = "development"
                 if (!config.isRootFunction()) {
                     continue; // Skip if not a root function config
                 }
+                if (this.functionFilter && config.name !== this.functionFilter) {
+                    continue;
+                }
                 functions.push(config);
             }
         }
         catch {
             // functions directory doesn't exist
         }
+        if (this.functionFilter && functions.length === 0) {
+            this.error(`Function '${this.functionFilter}' not found in ${style.path('functions/')}.`);
+        }
         return functions;
     }
     async logAllFunctions(functions) {
@@ -293,6 +306,9 @@ ENVIRONMENT = "development"
         if (appConfig?.type !== ConfigType.FUNCTION) {
             return;
         }
+        if (this.functionFilter && appConfig.name !== this.functionFilter) {
+            return;
+        }
         try {
             const fullPath = path.join(this.appPath, appConfig.filePath);
             // Re-bundle the function

package/dist/commands/app/frontend/dev.d.ts

@@ -10,6 +10,7 @@ export default class AppFrontendDev extends PushAppCommand {
         'no-push': import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
         port: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
         'frontend-port': import("@oclif/core/lib/interfaces/parser.js").OptionFlag<number | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        function: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
     };
     static orientation: {
         env: string;

package/dist/commands/logs.js

@@ -175,7 +175,7 @@ export default class Logs extends SwellCommand {
         type: Flags.string({
             description: 'filter logs by type',
             multiple: true,
-            options: ['api', 'function', 'webhook'],
+            options: ['api', 'function', 'webhook', 'transaction'],
         }),
     };
     static summary = 'Output or stream store logs to the terminal.';

package/dist/lib/apps/app-config.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+/// <reference types="node" />
 import { ConfigType } from './index.js';
 export declare class IgnoringFileError extends Error {
     constructor(message: string);

package/dist/lib/apps/index.d.ts

@@ -1,4 +1,5 @@
 /// <reference types="node" />
+/// <reference types="node" />
 import { AppConfig } from './app-config.js';
 export { AppConfig, FunctionProcessingError, IgnoringFileError, } from './app-config.js';
 export { allBaseFilesInDir, allConfigDirsPaths, allConfigFilesInDir, allConfigFilesPaths, allConfigFilesPathsByType, getAllConfigPaths, globAllFilesByPath, isPathDirectory, } from './paths.js';

package/dist/lib/swell-function-wrapper.d.ts

@@ -110,7 +110,7 @@ declare class SwellRequest {
      * @returns {object} existing app data merged with values
      * @throws {Error} if app id is missing or values is not a plain object
      */
-    appValues(idOrValues: object | string, values?: object | undefined): object;
+    appValues(idOrValues: object | string, values: object | undefined): object;
 }
 /**
  * Class representing the Swell backend API.
@@ -129,7 +129,36 @@ declare class SwellAPI {
     post(url: any, data: any): Promise<any>;
     delete(url: any, data: any): Promise<any>;
     settings(id?: any): Promise<any>;
+    /**
+     * Atomic multi-op write. Throws SwellError with a stable `error.code`
+     * (transaction_conflict | transaction_timeout | transaction_throttled
+     *  | transaction_op_failed | transaction_error). Retry is off by
+     * default — opt in with `{ retry: true }` or pass overrides.
+     *
+     * @param {Array<{method: string, url: string, data?: any}>} ops
+     * @param {{ retry?: true | { limit?: number, base?: number, max?: number, jitter?: boolean } }} [opts]
+     * @returns {Promise<any[]>}
+     */
+    transaction(ops: Array<{
+        method: string;
+        url: string;
+        data?: any;
+    }>, opts?: {
+        retry?: true | {
+            limit?: number | undefined;
+            base?: number | undefined;
+            max?: number | undefined;
+            jitter?: boolean | undefined;
+        } | undefined;
+    } | undefined): Promise<any[]>;
 }
+declare const DEFAULT_RETRY: Readonly<{
+    limit: 3;
+    base: 100;
+    max: 5000;
+    jitter: true;
+}>;
+declare const RETRYABLE_CODES: Set<string>;
 /**
  * Class representing a Swell error.
  */
@@ -137,6 +166,8 @@ declare class SwellError extends Error {
     constructor(message: any, options?: {});
     status: any;
     body: any;
+    code: any;
+    get isRetryable(): boolean;
 }
 /**
  * Class representing a Swell response.

package/dist/lib/swell-function-wrapper.js

@@ -23,10 +23,10 @@ async function request(originalRequest, _env, context) {
     try {
         response = await executeModuleHandler(req, context);
     }
-    catch (err) {
+    catch (error) {
         // Log the error for Swell
-        console.error(err);
-        response = new SwellResponse({ error: err.message }, { status: err.status || 500 });
+        console.error(error);
+        response = new SwellResponse({ error: error.message }, { status: error.status || 500 });
     }
     return SwellResponse._respond(req, response, context);
 }
@@ -71,11 +71,11 @@ async function executeModuleHandler(req, context) {
     if (moduleExports[method]) {
         return moduleExports[method](req, context);
     }
-    else if (defaults) {
+    if (defaults) {
         if (typeof defaults === 'function') {
             return defaults(req, context);
         }
-        else if (defaults[method]) {
+        if (defaults[method]) {
             return defaults[method](req, context);
         }
     }
@@ -120,9 +120,9 @@ class SwellRequest {
         this._logs = [];
     }
     assignRequestProps(req) {
-        ['ur', 'method', 'headers', 'referrer', 'credentials'].forEach((prop) => {
+        for (const prop of ['ur', 'method', 'headers', 'referrer', 'credentials']) {
             this[prop] = req[prop];
-        });
+        }
     }
     async initialize() {
         this.rawBody = await this.originalRequest.text();
@@ -131,15 +131,15 @@ class SwellRequest {
             this.data = JSON.parse(this.rawBody);
             this.body = { ...this.data };
         }
-        catch (err) {
+        catch {
             this.data = {};
         }
         this.url = new URL(this.originalRequest.url);
         // Convert the query parameters to an object
-        this.url.searchParams.forEach((value, key) => {
+        for (const [key, value] of this.url.searchParams.entries()) {
             this.query[key] = value;
             this.data[key] = value;
-        });
+        }
         // Bind the console methods to the request
         console.log = this.log.bind(this, 'info');
         console.info = this.log.bind(this, 'info');
@@ -151,7 +151,7 @@ class SwellRequest {
         try {
             return JSON.parse(input);
         }
-        catch (err) {
+        catch {
             return {};
         }
     }
@@ -160,7 +160,7 @@ class SwellRequest {
         this._logs.push({
             date: Date.now(),
             line: line.map((l) => (l instanceof Error ? l.stack : JSON.stringify(l))),
-            ...(level !== 'info' ? { level } : {}),
+            ...(level === 'info' ? {} : { level }),
         });
     }
     getIngestableLogs(response) {
@@ -186,7 +186,7 @@ class SwellRequest {
     formatRequestData() {
         try {
             const stringData = JSON.stringify(this.body ?? null);
-            return stringData.substring(0, 1024000);
+            return stringData.slice(0, 1024000);
         }
         catch {
             return '';
@@ -211,7 +211,7 @@ class SwellRequest {
      * @returns {object} existing app data merged with values
      * @throws {Error} if app id is missing or values is not a plain object
      */
-    appValues(idOrValues, values = undefined) {
+    appValues(idOrValues, values) {
         const appId = typeof idOrValues === 'string' ? idOrValues : this.appId;
         const appValues = typeof idOrValues === 'string' ? values : idOrValues;
         if (!appId) {
@@ -283,7 +283,7 @@ class SwellAPI {
                 throw new Error(`Error serializing data: ${data}`);
             }
         }
-        const endpointUrl = String(url).startsWith('/') ? url.substring(1) : url;
+        const endpointUrl = String(url).startsWith('/') ? url.slice(1) : url;
         const response = await fetch(`${this.baseUrl}/${endpointUrl}${query}`, requestOptions);
         const responseText = await response.text();
         let result;
@@ -320,7 +320,54 @@ class SwellAPI {
     async settings(id = this.request.appId) {
         return this.makeRequest('GET', `/settings/${id}`);
     }
+    /**
+     * Atomic multi-op write. Throws SwellError with a stable `error.code`
+     * (transaction_conflict | transaction_timeout | transaction_throttled
+     *  | transaction_op_failed | transaction_error). Retry is off by
+     * default — opt in with `{ retry: true }` or pass overrides.
+     *
+     * @param {Array<{method: string, url: string, data?: any}>} ops
+     * @param {{ retry?: true | { limit?: number, base?: number, max?: number, jitter?: boolean } }} [opts]
+     * @returns {Promise<any[]>}
+     */
+    async transaction(ops, opts = {}) {
+        if (!opts.retry) {
+            return this.makeRequest('POST', '/:transaction', ops);
+        }
+        const cfg = {
+            ...DEFAULT_RETRY,
+            ...(opts.retry === true ? {} : opts.retry),
+        };
+        let attempt = 0;
+        // eslint-disable-next-line no-constant-condition
+        while (true) {
+            try {
+                return await this.makeRequest('POST', '/:transaction', ops);
+            }
+            catch (error) {
+                if (!(error instanceof SwellError) ||
+                    !error.isRetryable ||
+                    attempt >= cfg.limit) {
+                    throw error;
+                }
+                const delay = Math.min(cfg.base * 2 ** attempt, cfg.max);
+                const wait = cfg.jitter ? delay * (0.5 + Math.random() * 0.5) : delay;
+                await new Promise((resolve) => setTimeout(resolve, wait));
+                attempt++;
+            }
+        }
+    }
 }
+const DEFAULT_RETRY = Object.freeze({
+    limit: 3,
+    base: 100,
+    max: 5000,
+    jitter: true,
+});
+const RETRYABLE_CODES = new Set([
+    'transaction_conflict',
+    'transaction_throttled',
+]);
 /**
  * Class representing a Swell error.
  */
@@ -331,6 +378,9 @@ class SwellError extends Error {
         if (typeof message === 'string') {
             formattedMessage = message;
         }
+        else if (typeof body?.error?.message === 'string') {
+            formattedMessage = body.error.message;
+        }
         else {
             formattedMessage = JSON.stringify(message, null, 2);
         }
@@ -341,6 +391,10 @@ class SwellError extends Error {
         this.name = 'SwellError';
         this.status = options.status || 500;
         this.body = body;
+        this.code = options.code || body?.error?.code;
+    }
+    get isRetryable() {
+        return RETRYABLE_CODES.has(this.code);
     }
 }
 /**
@@ -363,7 +417,7 @@ class SwellResponse extends Response {
             ...options,
             headers: {
                 ...resultHeaders,
-                ...(options.headers || {}),
+                ...options.headers,
             },
         });
         // Saved for future access
@@ -396,9 +450,9 @@ class SwellResponse extends Response {
     }
     static async _consumeNativeResponse(response) {
         const headers = {};
-        response.headers.forEach((value, key) => {
+        for (const [key, value] of response.headers.entries()) {
             headers[key] = value;
-        });
+        }
         try {
             const text = await response.text();
             let data;
@@ -413,8 +467,8 @@ class SwellResponse extends Response {
                 headers,
             });
         }
-        catch (err) {
-            return new SwellResponse({ error: `Unable to read response body: ${err.message}` }, { status: 500 });
+        catch (error) {
+            return new SwellResponse({ error: `Unable to read response body: ${error.message}` }, { status: 500 });
         }
     }
     static _respondWithLogs(response, req) {

package/oclif.manifest.json

@@ -217,7 +217,8 @@
           "options": [
             "api",
             "function",
-            "webhook"
+            "webhook",
+            "transaction"
           ],
           "type": "option"
         }
@@ -720,7 +721,8 @@
         "swell app dev",
         "swell app dev --storefront-id <id>",
         "swell app dev --port 3000",
-        "swell app dev --port 3000 --frontend-port 4000"
+        "swell app dev --port 3000 --frontend-port 4000",
+        "swell app dev --function my-function"
       ],
       "flags": {
         "app-path": {
@@ -751,6 +753,13 @@
           "multiple": false,
           "type": "option"
         },
+        "function": {
+          "description": "run only the named function",
+          "name": "function",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "storefront-id": {
           "description": "for storefront apps, identify a storefront to preview and push theme files to",
           "name": "storefront-id",
@@ -800,7 +809,7 @@
           "name": "versions"
         }
       },
-      "description": "The command shows the latest information about your app including the name,\ndescription, version, public ID, test store, and more. If the versions argument is passed,\nit will output all versions of the app instead.",
+      "description": "The command shows the latest information about your app including the name,\ndescription, version, public ID, test store, and more. If the \u001b[35m\u001b[1mversions\u001b[22m\u001b[39m argument is passed,\nit will output all versions of the app instead.",
       "examples": [
         {
           "command": "swell app info",
@@ -1099,7 +1108,7 @@
           "name": "targetPath"
         }
       },
-      "description": "Pull all app files, a specific file, or a specific configuration\ntype from an app in your store's test environment to your local machine.\n\nIf APPID is not specified, you will be prompted with a list of apps to choose from.\n\nApp file directories:\nassets/\ncontent/\nfrontend/\ncomponents/\nfunctions/\nmodels/\nnotifications/\nsettings/\ntheme/\nwebhooks/\nfrontend/",
+      "description": "Pull all app files, a specific file, or a specific configuration\ntype from an app in your store's test environment to your local machine.\n\nIf APPID is not specified, you will be prompted with a list of apps to choose from.\n\nApp file directories:\n\u001b[4massets/\u001b[24m\n\u001b[4mcontent/\u001b[24m\n\u001b[4mfrontend/\u001b[24m\n\u001b[4mcomponents/\u001b[24m\n\u001b[4mfunctions/\u001b[24m\n\u001b[4mmodels/\u001b[24m\n\u001b[4mnotifications/\u001b[24m\n\u001b[4msettings/\u001b[24m\n\u001b[4mtheme/\u001b[24m\n\u001b[4mwebhooks/\u001b[24m\n\u001b[4mfrontend/\u001b[24m",
       "examples": [
         "swell app pull",
         "swell app pull example_app",
@@ -1148,7 +1157,7 @@
           "name": "file"
         }
       },
-      "description": "Push all app files, a specific file, or a specific configuration\ntype to an app in your store's test environment.\n\nIf the app does not exist, it will be created and its global ID saved to a .swellrc file.\n\n- If no file is specified, all configuration files will be pushed to the store.\n  This includes the app icon (assets/icon.png) and swell.json.\n- If a file is specified, only that file will be pushed to the store.\n- If a directory is specified, only files in that directory will be pushed.\n\nApp file directories:\nassets/\ncontent/\nfrontend/\ncomponents/\nfunctions/\nmodels/\nnotifications/\nsettings/\ntheme/\nwebhooks/",
+      "description": "Push all app files, a specific file, or a specific configuration\ntype to an app in your store's test environment.\n\nIf the app does not exist, it will be created and its global ID saved to a .swellrc file.\n\n- If no file is specified, all configuration files will be pushed to the store.\n  This includes the app icon (assets/icon.png) and swell.json.\n- If a file is specified, only that file will be pushed to the store.\n- If a directory is specified, only files in that directory will be pushed.\n\nApp file directories:\n\u001b[4massets/\u001b[24m\n\u001b[4mcontent/\u001b[24m\n\u001b[4mfrontend/\u001b[24m\n\u001b[4mcomponents/\u001b[24m\n\u001b[4mfunctions/\u001b[24m\n\u001b[4mmodels/\u001b[24m\n\u001b[4mnotifications/\u001b[24m\n\u001b[4msettings/\u001b[24m\n\u001b[4mtheme/\u001b[24m\n\u001b[4mwebhooks/\u001b[24m",
       "examples": [
         "swell app push",
         "swell app push content",
@@ -3063,7 +3072,7 @@
           "name": "targetPath"
         }
       },
-      "description": "Pull all theme files, a specific file, or a specific configuration\ntype from a theme in your store's test environment to your local machine.\n\nIf APPID is not specified, you will be prompted with a list of themes to choose from.\n\nTheme file directories:\nassets/\ntheme/",
+      "description": "Pull all theme files, a specific file, or a specific configuration\ntype from a theme in your store's test environment to your local machine.\n\nIf APPID is not specified, you will be prompted with a list of themes to choose from.\n\nTheme file directories:\n\u001b[4massets/\u001b[24m\n\u001b[4mtheme/\u001b[24m",
       "examples": [
         "swell theme pull",
         "swell theme pull mytheme",
@@ -3134,7 +3143,7 @@
           "name": "file"
         }
       },
-      "description": "Push all theme files, a specific file, or a specific configuration\ntype to an theme in your store's test environment.\n\nIf the theme does not exist, it will be created and its global ID saved to a .swellrc file.\n\n- If no file is specified, all configuration files will be pushed to the store.\n  This includes the theme icon (assets/icon.png) and swell.json.\n- If a file is specified, only that file will be pushed to the store.\n- If a directory is specified, only files in that directory will be pushed.\n\nTheme file directories:\nassets/\ntheme/",
+      "description": "Push all theme files, a specific file, or a specific configuration\ntype to an theme in your store's test environment.\n\nIf the theme does not exist, it will be created and its global ID saved to a .swellrc file.\n\n- If no file is specified, all configuration files will be pushed to the store.\n  This includes the theme icon (assets/icon.png) and swell.json.\n- If a file is specified, only that file will be pushed to the store.\n- If a directory is specified, only files in that directory will be pushed.\n\nTheme file directories:\n\u001b[4massets/\u001b[24m\n\u001b[4mtheme/\u001b[24m",
       "examples": [
         "swell theme push",
         "swell theme push assets",
@@ -3307,6 +3316,13 @@
           "multiple": false,
           "type": "option"
         },
+        "function": {
+          "description": "run only the named function",
+          "name": "function",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "storefront-id": {
           "description": "identify a storefront to preview with and push theme files to",
           "name": "storefront-id",
@@ -3362,5 +3378,5 @@
       ]
     }
   },
-  "version": "2.7.1"
+  "version": "2.9.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swell/cli",
-  "version": "2.7.1",
+  "version": "2.9.0",
   "type": "module",
   "description": "Swell's command line interface/utility",
   "keywords": [
@@ -70,7 +70,7 @@
     "@types/inquirer": "9.0.6",
     "@types/localtunnel": "2.0.4",
     "@types/mocha": "10.0.3",
-    "@types/node": "20.8.8",
+    "@types/node": "22.10.0",
     "@types/qs": "6.9.15",
     "@types/ws": "8.18.1",
     "@typescript-eslint/eslint-plugin": "6.9.0",
@@ -121,7 +121,7 @@
     "publish-alpha": "npm version prerelease --preid=alpha && npm publish --tag alpha"
   },
   "engines": {
-    "node": ">= 18.16.1"
+    "node": ">= 22.0.0"
   },
   "types": "dist/index.d.ts"
 }