@swell/cli 2.5.7 → 2.6.0

package/dist/commands/api/delete.d.ts

@@ -9,6 +9,7 @@ export default class ApiDelete extends SwellApiCommand {
     static flags: {
         live: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
         api: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        header: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
     };
     static examples: string[];
     get method(): HttpMethod;

package/dist/commands/api/delete.js

@@ -1,6 +1,6 @@
 import { Args, Flags } from '@oclif/core';
 import { HttpMethod } from '../../lib/api.js';
-import { SwellApiCommand } from '../../swell-api-command.js';
+import { SwellApiCommand, headerFlag } from '../../swell-api-command.js';
 export default class ApiDelete extends SwellApiCommand {
     static summary = 'Send a DELETE request to the Swell API.';
     static description = `Remove existing resources from the Swell API.
@@ -21,10 +21,12 @@ export default class ApiDelete extends SwellApiCommand {
             options: ['backend', 'frontend'],
             default: 'backend',
         }),
+        header: headerFlag,
     };
     static examples = [
         'swell api delete /products/abc123',
         'swell api delete /functions/my-app/clear-cache',
+        `swell api delete /functions/my-app/clear-cache -H 'Authorization: Bearer xxx'`,
         'swell api delete /products/abc123 --api frontend',
     ];
     get method() {

package/dist/commands/api/get.d.ts

@@ -9,6 +9,7 @@ export default class ApiGet extends SwellApiCommand {
     static flags: {
         live: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
         api: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        header: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
     };
     static examples: string[];
     get method(): HttpMethod;

package/dist/commands/api/get.js

@@ -1,6 +1,6 @@
 import { Args, Flags } from '@oclif/core';
 import { HttpMethod } from '../../lib/api.js';
-import { SwellApiCommand } from '../../swell-api-command.js';
+import { SwellApiCommand, headerFlag } from '../../swell-api-command.js';
 export default class ApiGet extends SwellApiCommand {
     static summary = 'Send a GET request to the Swell API.';
     static description = `Retrieve data from the Swell API.
@@ -22,12 +22,14 @@ export default class ApiGet extends SwellApiCommand {
             options: ['backend', 'frontend'],
             default: 'backend',
         }),
+        header: headerFlag,
     };
     static examples = [
         'swell api get /products',
         'swell api get "/products?limit=10&category=shoes"',
         'swell api get /products/abc123',
         'swell api get /functions/my-app/get-inventory',
+        `swell api get /functions/my-app/get-inventory -H 'Authorization: Bearer xxx'`,
         'swell api get /products --api frontend',
     ];
     get method() {

package/dist/commands/api/post.d.ts

@@ -10,6 +10,7 @@ export default class ApiPost extends SwellApiCommand {
         body: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
         live: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
         api: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        header: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
     };
     static examples: string[];
     get method(): HttpMethod;

package/dist/commands/api/post.js

@@ -1,6 +1,6 @@
 import { Args, Flags } from '@oclif/core';
 import { HttpMethod } from '../../lib/api.js';
-import { SwellApiCommand } from '../../swell-api-command.js';
+import { SwellApiCommand, headerFlag } from '../../swell-api-command.js';
 export default class ApiPost extends SwellApiCommand {
     static summary = 'Send a POST request to the Swell API.';
     static description = `Create new resources in the Swell API.
@@ -25,11 +25,13 @@ export default class ApiPost extends SwellApiCommand {
             options: ['backend', 'frontend'],
             default: 'backend',
         }),
+        header: headerFlag,
     };
     static examples = [
         'swell api post /products --body \'{"name": "Product", "price": 100}\'',
         'swell api post /products --body ./product.json',
         'swell api post /functions/my-app/create-order --body \'{"items":["sku-1"]}\'',
+        `swell api post /functions/my-app/webhook --body @./payload.json -H 'Stripe-Signature: t=123,v1=abc'`,
         `swell api post /products --body '{"name": "Product"}' --api frontend`,
     ];
     get method() {

package/dist/commands/api/put.d.ts

@@ -10,6 +10,7 @@ export default class ApiPut extends SwellApiCommand {
         body: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
         live: import("@oclif/core/lib/interfaces/parser.js").BooleanFlag<boolean>;
         api: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
+        header: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
     };
     static examples: string[];
     get method(): HttpMethod;

package/dist/commands/api/put.js

@@ -1,6 +1,6 @@
 import { Args, Flags } from '@oclif/core';
 import { HttpMethod } from '../../lib/api.js';
-import { SwellApiCommand } from '../../swell-api-command.js';
+import { SwellApiCommand, headerFlag } from '../../swell-api-command.js';
 export default class ApiPut extends SwellApiCommand {
     static summary = 'Send a PUT request to the Swell API.';
     static description = `Update existing resources in the Swell API.
@@ -25,11 +25,13 @@ export default class ApiPut extends SwellApiCommand {
             options: ['backend', 'frontend'],
             default: 'backend',
         }),
+        header: headerFlag,
     };
     static examples = [
         'swell api put /products/{id} --body \'{"id": "abc123", "name": "Updated"}\'',
         'swell api put /products/abc123 --body ./product.json',
         'swell api put /functions/my-app/update-stock --body \'{"sku":"abc","qty":10}\'',
+        `swell api put /functions/my-app/update-stock --body '{"sku":"abc"}' -H 'X-Idempotency-Key: 42'`,
         `swell api put /products/abc123 --body '{"name": "Updated"}' --api frontend`,
     ];
     get method() {

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

@@ -1,3 +1,5 @@
+/// <reference types="node" />
+import { ChildProcess } from 'node:child_process';
 import { PushAppCommand } from '../../push-app-command.js';
 export default class AppDev extends PushAppCommand {
     static delayOrientation: boolean;
@@ -16,6 +18,7 @@ export default class AppDev extends PushAppCommand {
     static summary: string;
     functionErrors: Map<string, string>;
     functionPorts: Map<string, number>;
+    functionProcesses: Map<string, ChildProcess>;
     tmpDir: string;
     frontendPort: number | null;
     isCleaningUp: boolean;

package/dist/commands/app/dev.js

@@ -50,6 +50,8 @@ export default class AppDev extends PushAppCommand {
     functionErrors = new Map();
     // All available functions
     functionPorts = new Map();
+    // Wrangler child processes to kill on cleanup
+    functionProcesses = new Map();
     // Directory for compiled function files and wrangler context
     tmpDir = '';
     // Port for frontend dev server (used for routing non-function requests)
@@ -84,6 +86,9 @@ export default class AppDev extends PushAppCommand {
         if (this.isCleaningUp)
             return;
         this.isCleaningUp = true;
+        for (const [, proc] of this.functionProcesses) {
+            proc.kill();
+        }
         try {
             await this.updateLocalProxy(null, this.storefront?.id);
         }
@@ -252,11 +257,8 @@ ENVIRONMENT = "development"
                         .map((m) => String(m).toUpperCase())
                         .join(', '))}`);
                 }
-                if (config.route.headers) {
-                    const headers = Object.entries(config.route.headers).map(([key, value]) => `${key}: ${value}`);
-                    this.log(`    Headers:`);
-                    for (const header of headers)
-                        this.log(`      ${style.dim(header)}`);
+                if (config.route.headers?.length) {
+                    this.log(`    Headers: ${style.dim(config.route.headers.join(', '))}`);
                 }
                 if (config.route.cache?.timeout) {
                     this.log(`    Cache timeout: ${style.dim(config.route.cache.timeout)}`);
@@ -296,7 +298,9 @@ ENVIRONMENT = "development"
             // Re-bundle the function
             const { code } = await bundleFunction(fullPath);
             // Update the bundled file (wrangler dev will auto-reload)
-            const bundledPath = path.join(this.tmpDir, `${appConfig.name}.js`);
+            const functionDir = path.join(this.tmpDir, `${appConfig.name}`);
+            await fs.promises.mkdir(functionDir, { recursive: true });
+            const bundledPath = path.join(functionDir, `${appConfig.name}.js`);
             await fs.promises.writeFile(bundledPath, code);
             if (this.functionPorts.has(appConfig.name)) {
                 this.log(`\nUpdating function ${appConfig.name}...`);
@@ -355,6 +359,7 @@ ENVIRONMENT = "development"
     }
     async startFunctionServers(functions) {
         const functionStatus = new Map();
+        const allocatedFunctionPorts = new Set();
         const allocatedInspectorPorts = new Set();
         /* eslint-disable no-await-in-loop */
         for (const func of functions) {
@@ -363,7 +368,11 @@ ENVIRONMENT = "development"
                 // Function server already running
                 continue;
             }
-            const functionPort = await getPort({ port: portNumbers(9000, 9100) });
+            const functionPort = await getPort({
+                port: portNumbers(9000, 9100),
+                exclude: [...allocatedFunctionPorts],
+            });
+            allocatedFunctionPorts.add(functionPort);
             const inspectorPort = await getPort({
                 port: portNumbers(9229, 9329),
                 exclude: [...allocatedInspectorPorts],
@@ -373,12 +382,15 @@ ENVIRONMENT = "development"
                 // Bundle the function
                 const fullPath = path.join(this.appPath, func.filePath);
                 const { code } = await bundleFunction(fullPath);
-                // Write bundled function to tmp directory
-                const bundledPath = path.join(this.tmpDir, `${functionName}.js`);
+                // Each function gets its own directory to avoid wrangler state conflicts
+                const functionDir = path.join(this.tmpDir, functionName);
+                await fs.promises.mkdir(functionDir, { recursive: true });
+                // Write bundled function to its directory
+                const bundledPath = path.join(functionDir, `${functionName}.js`);
                 await fs.promises.writeFile(bundledPath, code);
                 // Generate wrangler config
                 const wranglerConfig = this.generateWranglerConfig(functionName, bundledPath);
-                const configPath = path.join(this.tmpDir, `${functionName}.toml`);
+                const configPath = path.join(functionDir, `${functionName}.toml`);
                 await fs.promises.writeFile(configPath, wranglerConfig);
                 functionStatus.set(functionName, 'starting');
                 // Start wrangler process in background using detected package manager
@@ -392,7 +404,7 @@ ENVIRONMENT = "development"
                     `--port=${functionPort}`,
                     `--inspector-port=${inspectorPort}`,
                 ], {
-                    cwd: this.tmpDir,
+                    cwd: functionDir,
                     // stdio: 'pipe', // Capture output for debugging
                     detached: false,
                 });
@@ -458,7 +470,8 @@ ENVIRONMENT = "development"
                         this.functionErrors.set(functionName, `Process exited with code ${code}`);
                     }
                 });
-                // Store the port for routing
+                // Store the process and port for routing
+                this.functionProcesses.set(functionName, wranglerProcess);
                 this.functionPorts.set(functionName, functionPort);
             }
             catch (error) {

package/dist/lib/create/tests/templates/mock-request.js

@@ -97,7 +97,18 @@ export function createMockRequest(options: MockRequestOptions = {}): SwellReques
       const targetAppId =
         typeof idOrValues === "string" ? idOrValues : resolvedAppId;
       const appValues = typeof idOrValues === "string" ? values : idOrValues;
-      if (!targetAppId || !appValues) return undefined;
+      if (!targetAppId) {
+        throw new Error("appValues: missing app id (req.appId is empty)");
+      }
+      if (
+        typeof appValues !== "object" ||
+        appValues === null ||
+        Object.getPrototypeOf(appValues) !== Object.prototype
+      ) {
+        throw new Error(
+          "appValues: values must be a plain object (arrays, class instances, null, and primitives are not allowed)"
+        );
+      }
       return {
         $app: {
           [targetAppId]: appValues,

package/dist/lib/create/tests/templates/setup-globals.js

@@ -2,6 +2,7 @@ export function setupGlobalsTemplate() {
     return `\
 class SwellErrorImpl extends Error {
   status: number;
+  body?: unknown;
 
   constructor(message: string | object, options: { status?: number } = {}) {
     const text =
@@ -12,6 +13,7 @@ class SwellErrorImpl extends Error {
     super(text);
     this.name = "SwellError";
     this.status = options.status ?? 500;
+    this.body = typeof message === "string" ? undefined : message;
   }
 }
 

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

@@ -88,6 +88,7 @@ declare class SwellRequest {
     id: any;
     isLocalDev: boolean;
     swell: SwellAPI;
+    rawBody: string;
     body: {};
     query: {};
     data: {};
@@ -100,14 +101,16 @@ declare class SwellRequest {
     getIngestableLogs(response: any): {
         params: any;
     } | undefined;
+    formatRequestData(): string;
     ingestLogs(response: any): Promise<void>;
     /**
      * Merge values into app data for the current request.
      * @param {object|string} idOrValues string to indicate app ID, or values to merge
      * @param {object|undefined} values values to merge into app data
-     * @returns {object|undefined} existing app data merged with values if passed
+     * @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 | undefined;
+    appValues(idOrValues: object | string, values?: object | undefined): object;
 }
 /**
  * Class representing the Swell backend API.
@@ -133,12 +136,14 @@ declare class SwellAPI {
 declare class SwellError extends Error {
     constructor(message: any, options?: {});
     status: any;
+    body: any;
 }
 /**
  * Class representing a Swell response.
  */
 declare class SwellResponse extends Response {
-    static _respond(req: any, response: any, context: any): any;
+    static _respond(req: any, response: any, context: any): Promise<any>;
+    static _consumeNativeResponse(response: any): Promise<SwellResponse>;
     static _respondWithLogs(response: any, req: any): SwellResponse;
     constructor(data: any, options?: {});
     _swellData: any;

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

@@ -90,6 +90,8 @@ class SwellRequest {
         this.assignRequestProps(req);
         // Set environment specific variables
         this.context = context;
+        // Slug-form app identifier (e.g. 'klaviyo') matching keys in record.$app[...].
+        // Derived from the app's private_id with the leading underscore stripped.
         this.appId = req.headers.get('Swell-App-Id');
         this.storeId = req.headers.get('Swell-Store-Id');
         this.accessToken = req.headers.get('Swell-Access-Token');
@@ -105,11 +107,14 @@ class SwellRequest {
         this.swell = new SwellAPI(this, context);
         // URL of the original request
         this.url;
-        // Original body of the request, JSON if applicable
+        // Raw request body text, untouched by parsing.
+        // Use on route triggers for HMAC/webhook signature verification.
+        this.rawBody = '';
+        // Parsed JSON body as object, or raw text string when body isn't JSON.
         this.body = {};
         // URL query parameters as an object
         this.query = {};
-        // Combined object of body and query parameters
+        // Combined object of body and query parameters (query keys overwrite body keys)
         this.data = {};
         // Internal logs
         this._logs = [];
@@ -120,9 +125,10 @@ class SwellRequest {
         });
     }
     async initialize() {
-        this.body = await this.originalRequest.text();
+        this.rawBody = await this.originalRequest.text();
+        this.body = this.rawBody;
         try {
-            this.data = JSON.parse(this.body);
+            this.data = JSON.parse(this.rawBody);
             this.body = { ...this.data };
         }
         catch (err) {
@@ -170,12 +176,22 @@ class SwellRequest {
                 ...this.logParams,
                 message: {
                     ...this.logParams?.message,
+                    data: this.logParams?.message?.data || this.formatRequestData(),
                     logs: this._logs,
                     status: response.status,
                 },
             },
         };
     }
+    formatRequestData() {
+        try {
+            const stringData = JSON.stringify(this.body ?? null);
+            return stringData.substring(0, 1024000);
+        }
+        catch {
+            return '';
+        }
+    }
     async ingestLogs(response) {
         const ingestableLogs = this.getIngestableLogs(response);
         if (!ingestableLogs) {
@@ -192,13 +208,17 @@ class SwellRequest {
      * Merge values into app data for the current request.
      * @param {object|string} idOrValues string to indicate app ID, or values to merge
      * @param {object|undefined} values values to merge into app data
-     * @returns {object|undefined} existing app data merged with values if passed
+     * @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) {
-        const appId = typeof idOrValues === 'string' ? appIdOrValues : this.appId;
+        const appId = typeof idOrValues === 'string' ? idOrValues : this.appId;
         const appValues = typeof idOrValues === 'string' ? values : idOrValues;
-        if (!appId || !isOrdinaryObject(appValues)) {
-            return undefined;
+        if (!appId) {
+            throw new Error('appValues: missing app id (req.appId is empty)');
+        }
+        if (!isOrdinaryObject(appValues)) {
+            throw new Error('appValues: values must be a plain object (arrays, class instances, null, and primitives are not allowed)');
         }
         return {
             $app: {
@@ -306,6 +326,7 @@ class SwellAPI {
  */
 class SwellError extends Error {
     constructor(message, options = {}) {
+        const body = typeof message === 'string' ? undefined : message;
         let formattedMessage;
         if (typeof message === 'string') {
             formattedMessage = message;
@@ -319,6 +340,7 @@ class SwellError extends Error {
         super(formattedMessage);
         this.name = 'SwellError';
         this.status = options.status || 500;
+        this.body = body;
     }
 }
 /**
@@ -348,27 +370,53 @@ class SwellResponse extends Response {
         this._swellData = data;
         this._swellOptions = options || {};
     }
-    static _respond(req, response, context) {
+    static async _respond(req, response, context) {
         let finalResponse = response;
-        // Convert a plain Response instance to SwellResponse
+        const isHook = Boolean(req.data?.$event?.hook);
         if (finalResponse instanceof Response &&
             !(finalResponse instanceof SwellResponse)) {
-            finalResponse = new SwellResponse(response.body, {
-                status: response.status,
-                headers: response.headers,
-            });
+            // Non-hook responses pass through unchanged so the handler's body,
+            // status, and headers reach the caller intact. Hooks need the parsed
+            // body so $logs can be merged into the payload below.
+            if (isHook) {
+                finalResponse =
+                    await SwellResponse._consumeNativeResponse(finalResponse);
+            }
         }
         else if (!(finalResponse instanceof SwellResponse)) {
             finalResponse = new SwellResponse(response);
         }
         // Send logs back with the response for event hooks
-        if (req.data?.$event?.hook) {
+        if (isHook) {
             return SwellResponse._respondWithLogs(finalResponse, req);
         }
         // Ingest logs in the background
         context.waitUntil(req.ingestLogs(finalResponse));
         return finalResponse;
     }
+    static async _consumeNativeResponse(response) {
+        const headers = {};
+        response.headers.forEach((value, key) => {
+            headers[key] = value;
+        });
+        try {
+            const text = await response.text();
+            let data;
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                data = text;
+            }
+            return new SwellResponse(data, {
+                status: response.status,
+                headers,
+            });
+        }
+        catch (err) {
+            return new SwellResponse({ error: `Unable to read response body: ${err.message}` }, { status: 500 });
+        }
+    }
     static _respondWithLogs(response, req) {
         const ingestableLogs = req.getIngestableLogs(response);
         // Rebuild response with logs

package/dist/swell-api-command.d.ts

@@ -1,5 +1,6 @@
 import { HttpMethod } from './lib/api.js';
 import { SwellCommand } from './swell-command.js';
+export declare const headerFlag: import("@oclif/core/lib/interfaces/parser.js").OptionFlag<string[] | undefined, import("@oclif/core/lib/interfaces/parser.js").CustomOptions>;
 export declare abstract class SwellApiCommand extends SwellCommand {
     protected abstract get method(): HttpMethod;
     protected request(command: typeof SwellApiCommand, requestOptions?: Api.RequestOptions): Promise<void>;
@@ -18,6 +19,7 @@ export declare abstract class SwellApiCommand extends SwellCommand {
      * Build a function invocation request via the admin /:functions endpoint.
      */
     private buildFunctionCallRequest;
+    private parseHeaders;
     private parseQueryString;
     private processBody;
     private isFilePath;

package/dist/swell-api-command.js

@@ -1,3 +1,4 @@
+import { Flags } from '@oclif/core';
 import * as fs from 'node:fs';
 import path from 'node:path';
 import { FetchError } from 'node-fetch';
@@ -7,6 +8,13 @@ import { SwellCommand } from './swell-command.js';
 const FUNCTION_PATH_REGEX = /^\/functions\/([^/]+)\/([^/?]+)(\?.*)?$/;
 // Pattern to match /functions/{functionId} with optional query string
 const FUNCTION_DIRECT_REGEX = /^\/functions\/([^/?]+)(\?.*)?$/;
+// Shared --header / -H flag for function-call paths. Pass once per header.
+// Only forwarded as $call.headers on /functions/* paths; ignored elsewhere.
+export const headerFlag = Flags.string({
+    char: 'H',
+    description: "HTTP header to forward to a function (format: 'Name: value'). Repeat for multiple. Only applies to /functions/* paths.",
+    multiple: true,
+});
 export class SwellApiCommand extends SwellCommand {
     async request(command, requestOptions = {}) {
         const { paths, options, methodOverride } = await this.parseCommand(command);
@@ -29,7 +37,7 @@ export class SwellApiCommand extends SwellCommand {
         const parsedInput = await super.parse(options, argv);
         const { args, flags } = parsedInput;
         const { path: requestPath } = args;
-        const { live, api, body } = flags;
+        const { live, api, body, header } = flags;
         const isFrontendAPI = api === 'frontend';
         if (!live) {
             await this.api.setEnv('test');
@@ -41,21 +49,30 @@ export class SwellApiCommand extends SwellCommand {
             throw new Error('Path must start with a forward slash (/)');
         }
         const processedBody = await this.processBody(body);
+        const callHeaders = this.parseHeaders(header);
         // Check if this is a function call by name: /functions/{appId}/{functionName}
         // Must check this first (more specific pattern)
         const functionMatch = requestPath.match(FUNCTION_PATH_REGEX);
         if (functionMatch) {
             const [, appId, functionName, queryString] = functionMatch;
             const functionId = await this.resolveFunctionId(appId, functionName);
-            const queryParams = this.parseQueryString(queryString);
-            return this.buildFunctionCallRequest(parsedInput, functionId, processedBody, queryParams);
+            return this.buildFunctionCallRequest(parsedInput, {
+                functionId,
+                body: processedBody,
+                query: this.parseQueryString(queryString),
+                headers: callHeaders,
+            });
         }
         // Check if this is a direct function call: /functions/{functionId}
         const directMatch = requestPath.match(FUNCTION_DIRECT_REGEX);
         if (directMatch) {
             const [, functionId, queryString] = directMatch;
-            const queryParams = this.parseQueryString(queryString);
-            return this.buildFunctionCallRequest(parsedInput, functionId, processedBody, queryParams);
+            return this.buildFunctionCallRequest(parsedInput, {
+                functionId,
+                body: processedBody,
+                query: this.parseQueryString(queryString),
+                headers: callHeaders,
+            });
         }
         const paths = isFrontendAPI
             ? { frontendPath: requestPath }
@@ -108,27 +125,49 @@ export class SwellApiCommand extends SwellCommand {
     /**
      * Build a function invocation request via the admin /:functions endpoint.
      */
-    buildFunctionCallRequest(parsedInput, functionId, bodyData, queryParams) {
+    buildFunctionCallRequest(parsedInput, call) {
         // Merge query params with body data (body takes precedence)
-        // Only merge if bodyData is a plain object; otherwise use bodyData or query params alone
-        const mergedData = this.isPlainObject(bodyData)
-            ? { ...queryParams, ...bodyData }
-            : bodyData ?? queryParams;
-        const callBody = {
-            $call: {
-                data: mergedData,
-                method: this.method,
-            },
+        // Only merge if body is a plain object; otherwise use body or query alone
+        const mergedData = this.isPlainObject(call.body)
+            ? { ...call.query, ...call.body }
+            : call.body ?? call.query;
+        const $call = {
+            data: mergedData,
+            method: this.method,
         };
+        if (Object.keys(call.headers).length > 0) {
+            $call.headers = call.headers;
+        }
         return {
             ...parsedInput,
-            paths: { adminPath: `/data/:functions/${functionId}` },
+            paths: { adminPath: `/data/:functions/${call.functionId}` },
             options: {
-                body: callBody,
+                body: { $call },
             },
             methodOverride: HttpMethod.PUT,
         };
     }
+    // Parse repeated `-H "Name: value"` flag entries into a map. Splits on first colon
+    // so values containing colons (e.g. `Authorization: Bearer x:y`) survive intact.
+    parseHeaders(headerArgs) {
+        if (!headerArgs?.length) {
+            return {};
+        }
+        const result = {};
+        for (const entry of headerArgs) {
+            const colonIndex = entry.indexOf(':');
+            if (colonIndex < 1) {
+                throw new Error(`Invalid header '${entry}'. Expected format: 'Name: value'.`);
+            }
+            const name = entry.slice(0, colonIndex).trim();
+            const value = entry.slice(colonIndex + 1).trim();
+            if (!name) {
+                throw new Error(`Invalid header '${entry}'. Header name cannot be empty.`);
+            }
+            result[name] = value;
+        }
+        return result;
+    }
     parseQueryString(queryString) {
         if (!queryString) {
             return {};

package/oclif.manifest.json

@@ -385,6 +385,7 @@
       "examples": [
         "swell api delete /products/abc123",
         "swell api delete /functions/my-app/clear-cache",
+        "swell api delete /functions/my-app/clear-cache -H 'Authorization: Bearer xxx'",
         "swell api delete /products/abc123 --api frontend"
       ],
       "flags": {
@@ -405,6 +406,14 @@
             "frontend"
           ],
           "type": "option"
+        },
+        "header": {
+          "char": "H",
+          "description": "HTTP header to forward to a function (format: 'Name: value'). Repeat for multiple. Only applies to /functions/* paths.",
+          "name": "header",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -438,6 +447,7 @@
         "swell api get \"/products?limit=10&category=shoes\"",
         "swell api get /products/abc123",
         "swell api get /functions/my-app/get-inventory",
+        "swell api get /functions/my-app/get-inventory -H 'Authorization: Bearer xxx'",
         "swell api get /products --api frontend"
       ],
       "flags": {
@@ -458,6 +468,14 @@
             "frontend"
           ],
           "type": "option"
+        },
+        "header": {
+          "char": "H",
+          "description": "HTTP header to forward to a function (format: 'Name: value'). Repeat for multiple. Only applies to /functions/* paths.",
+          "name": "header",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -521,6 +539,7 @@
         "swell api post /products --body '{\"name\": \"Product\", \"price\": 100}'",
         "swell api post /products --body ./product.json",
         "swell api post /functions/my-app/create-order --body '{\"items\":[\"sku-1\"]}'",
+        "swell api post /functions/my-app/webhook --body @./payload.json -H 'Stripe-Signature: t=123,v1=abc'",
         "swell api post /products --body '{\"name\": \"Product\"}' --api frontend"
       ],
       "flags": {
@@ -548,6 +567,14 @@
             "frontend"
           ],
           "type": "option"
+        },
+        "header": {
+          "char": "H",
+          "description": "HTTP header to forward to a function (format: 'Name: value'). Repeat for multiple. Only applies to /functions/* paths.",
+          "name": "header",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -580,6 +607,7 @@
         "swell api put /products/{id} --body '{\"id\": \"abc123\", \"name\": \"Updated\"}'",
         "swell api put /products/abc123 --body ./product.json",
         "swell api put /functions/my-app/update-stock --body '{\"sku\":\"abc\",\"qty\":10}'",
+        "swell api put /functions/my-app/update-stock --body '{\"sku\":\"abc\"}' -H 'X-Idempotency-Key: 42'",
         "swell api put /products/abc123 --body '{\"name\": \"Updated\"}' --api frontend"
       ],
       "flags": {
@@ -607,6 +635,14 @@
             "frontend"
           ],
           "type": "option"
+        },
+        "header": {
+          "char": "H",
+          "description": "HTTP header to forward to a function (format: 'Name: value'). Repeat for multiple. Only applies to /functions/* paths.",
+          "name": "header",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
         }
       },
       "hasDynamicHelp": false,
@@ -2969,5 +3005,5 @@
       ]
     }
   },
-  "version": "2.5.7"
+  "version": "2.6.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swell/cli",
-  "version": "2.5.7",
+  "version": "2.6.0",
   "type": "module",
   "description": "Swell's command line interface/utility",
   "keywords": [