@swell/cli 2.5.8 → 2.7.0

package/dist/lib/inspect/settings.d.ts

@@ -0,0 +1,61 @@
+import { GroupInfo } from './table.js';
+export interface SettingRecord {
+    api?: string;
+    app_id?: string | null;
+    deprecated?: boolean | null;
+    fields?: Record<string, unknown>;
+    id?: string;
+    label?: string;
+    name?: string;
+}
+/**
+ * Settings identifier grammar (calibrated against `/data/:settings`).
+ *
+ *   `app.<slug-or-hex>` → kind 'app'  — slug must be translated to hex before
+ *                                       a path GET; hex passes through.
+ *   anything else valid → kind 'path' — direct path GET. The endpoint resolves
+ *                                       bare system names (`taxes`), bare app
+ *                                       hexes, and full dotted ids
+ *                                       (`com.taxes`) on the path. No `name`
+ *                                       query needed.
+ *   anything else      → kind 'invalid'
+ *
+ * The 3-segment `app.<slug>.<name>` form is rejected: settings collapse to one
+ * record per app at push time, so there is no sub-section identity the API can
+ * resolve back. Users wanting a single section run `--json | jq`.
+ */
+export type ParsedSettingsKey = {
+    kind: 'app';
+    ref: string;
+} | {
+    kind: 'path';
+    segment: string;
+} | {
+    input: string;
+    kind: 'invalid';
+};
+export declare function parseSettingsKey(input: string): ParsedSettingsKey;
+/**
+ * Produce the column-1 paste-back key for a settings record.
+ *
+ *   System (no app_id):  `record.name` (e.g. `taxes`).
+ *   App with slug:       `app.<slug>`.
+ *   App without slug:    `app.<hex>` (still pasteable — `app.<hex>` resolves).
+ *
+ * App records carry `name === app_id` (the hex), which is meaningless to a
+ * human; we never surface it. Ultimate fallback is `record.id` for degenerate
+ * records that have neither `app_id` nor `name`.
+ */
+export declare function formatSettingsKey(record: SettingRecord, appSlugById: Record<string, string>): string;
+/**
+ * Group a settings record. System rows (`app_id` null/undefined) belong to the
+ * platform and render under a `system` divider at the top, mirroring the
+ * notifications shape.
+ */
+export declare function groupSettingsRecord(record: SettingRecord, appSlugById: Record<string, string>): GroupInfo;
+/**
+ * `general` and `admin` are flagged `deprecated: true` in the base schema and
+ * still come back from the default list (no server-side filter equivalent —
+ * `deprecated[$ne]=true` doesn't take). Filter them out client-side.
+ */
+export declare function isDeprecatedRecord(record: SettingRecord): boolean;

package/dist/lib/inspect/settings.js

@@ -0,0 +1,56 @@
+const PATH_SEGMENT = /^[\w.-]+$/;
+const APP_PREFIX = /^app\.([^.]+)$/;
+export function parseSettingsKey(input) {
+    const appMatch = input.match(APP_PREFIX);
+    if (appMatch) {
+        return { kind: 'app', ref: appMatch[1] };
+    }
+    if (input.startsWith('app.')) {
+        return { kind: 'invalid', input };
+    }
+    if (PATH_SEGMENT.test(input)) {
+        return { kind: 'path', segment: input };
+    }
+    return { kind: 'invalid', input };
+}
+/**
+ * Produce the column-1 paste-back key for a settings record.
+ *
+ *   System (no app_id):  `record.name` (e.g. `taxes`).
+ *   App with slug:       `app.<slug>`.
+ *   App without slug:    `app.<hex>` (still pasteable — `app.<hex>` resolves).
+ *
+ * App records carry `name === app_id` (the hex), which is meaningless to a
+ * human; we never surface it. Ultimate fallback is `record.id` for degenerate
+ * records that have neither `app_id` nor `name`.
+ */
+export function formatSettingsKey(record, appSlugById) {
+    if (!record.app_id) {
+        return record.name ?? record.id ?? '-';
+    }
+    const slug = appSlugById[record.app_id] ?? record.app_id;
+    return `app.${slug}`;
+}
+/**
+ * Group a settings record. System rows (`app_id` null/undefined) belong to the
+ * platform and render under a `system` divider at the top, mirroring the
+ * notifications shape.
+ */
+export function groupSettingsRecord(record, appSlugById) {
+    if (!record.app_id) {
+        return { slug: '<system>', label: 'system', order: 0 };
+    }
+    const resolved = appSlugById[record.app_id];
+    if (!resolved) {
+        return { slug: '<not resolved>', order: 2 };
+    }
+    return { slug: resolved };
+}
+/**
+ * `general` and `admin` are flagged `deprecated: true` in the base schema and
+ * still come back from the default list (no server-side filter equivalent —
+ * `deprecated[$ne]=true` doesn't take). Filter them out client-side.
+ */
+export function isDeprecatedRecord(record) {
+    return record.deprecated === true;
+}

package/dist/lib/inspect/table.d.ts

@@ -0,0 +1,29 @@
+export interface GroupInfo {
+    /** Grouping identity. Rows with the same slug land in the same section. */
+    slug: string;
+    /** Divider text. Defaults to `slug` when omitted. */
+    label?: string;
+    /** Sort priority; lower renders first. Ties preserve insertion order. Default 1. */
+    order?: number;
+}
+export interface KeyMetaRow {
+    /** Paste-back identifier rendered as column 1. */
+    key: string;
+    /** Optional compact status string. Empty or undefined renders the key alone. */
+    meta?: string;
+    /** Optional group; when some rows carry one, multiple groups produce dividers. */
+    group?: GroupInfo;
+}
+/**
+ * Render a two-column list: paste-back key + optional compact meta string.
+ *
+ * - Rows with meta render as `  <key-padded>  <meta>`.
+ * - Rows without meta render as `  <key>` with no trailing whitespace.
+ * - Key column width is computed globally across all rows so meta columns
+ *   align vertically.
+ * - Rows with a `group` are collected into sections; sections are separated
+ *   by a blank line and a `── <label>` divider. Sections sort by `order`
+ *   (lower first), ties preserve insertion order. A single group collapses
+ *   to a flat listing.
+ */
+export declare function renderKeyMetaTable(rows: KeyMetaRow[]): string[];

package/dist/lib/inspect/table.js

@@ -0,0 +1,61 @@
+/**
+ * Render a two-column list: paste-back key + optional compact meta string.
+ *
+ * - Rows with meta render as `  <key-padded>  <meta>`.
+ * - Rows without meta render as `  <key>` with no trailing whitespace.
+ * - Key column width is computed globally across all rows so meta columns
+ *   align vertically.
+ * - Rows with a `group` are collected into sections; sections are separated
+ *   by a blank line and a `── <label>` divider. Sections sort by `order`
+ *   (lower first), ties preserve insertion order. A single group collapses
+ *   to a flat listing.
+ */
+export function renderKeyMetaTable(rows) {
+    if (rows.length === 0) {
+        return [];
+    }
+    const keyWidth = Math.max(...rows.map((r) => r.key.length));
+    const formatRow = (row) => {
+        if (row.meta && row.meta.length > 0) {
+            return `  ${row.key.padEnd(keyWidth)}  ${row.meta}`;
+        }
+        return `  ${row.key}`;
+    };
+    const hasGroups = rows.some((r) => r.group !== undefined);
+    if (!hasGroups) {
+        return rows.map((row) => formatRow(row));
+    }
+    const groupMap = new Map();
+    for (const row of rows) {
+        const info = row.group;
+        if (!info)
+            continue;
+        const existing = groupMap.get(info.slug);
+        if (existing) {
+            existing.rows.push(row);
+        }
+        else {
+            groupMap.set(info.slug, {
+                slug: info.slug,
+                label: info.label ?? info.slug,
+                order: info.order ?? 1,
+                rows: [row],
+            });
+        }
+    }
+    if (groupMap.size === 1) {
+        return rows.map((row) => formatRow(row));
+    }
+    const ordered = [...groupMap.values()].sort((a, b) => a.order - b.order);
+    const lines = [];
+    for (const group of ordered) {
+        if (lines.length > 0) {
+            lines.push('');
+        }
+        lines.push(`── ${group.label}`);
+        for (const row of group.rows) {
+            lines.push(formatRow(row));
+        }
+    }
+    return lines;
+}

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: {};
@@ -106,9 +107,10 @@ declare 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: object | string, values?: object | undefined): object | undefined;
+    appValues(idOrValues: object | string, values?: object | undefined): object;
 }
 /**
  * Class representing the Swell backend API.
@@ -134,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) {
@@ -202,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: {
@@ -316,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;
@@ -329,6 +340,7 @@ class SwellError extends Error {
         super(formattedMessage);
         this.name = 'SwellError';
         this.status = options.status || 500;
+        this.body = body;
     }
 }
 /**
@@ -358,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/push-app-command.js

@@ -6,8 +6,9 @@ import * as path from 'node:path';
 import Stream from 'node:stream';
 import ora from 'ora';
 import { default as swellConfig } from './lib/app-config.js';
-import { ConfigType, getFrontendProjectValidValues, allConfigFilesInDir, CUSTOM_FRAMEWORK_SLUG, appConfigFromFile, filePathExists, filePathExistsAsync, findAppConfig, getAppSlugId, getConfigTypeFromPath, getConfigTypeKeyFromValue, getFrontendProjectType, getProjectCommands, globAllFilesByPath, hashString, isPathDirectory, } from './lib/apps/index.js';
+import { ConfigType, getFrontendProjectValidValues, allConfigFilesInDir, CUSTOM_FRAMEWORK_SLUG, appConfigFromFile, filePathExists, filePathExistsAsync, findAppConfig, getConfigTypeFromPath, getConfigTypeKeyFromValue, getFrontendProjectType, getProjectCommands, globAllFilesByPath, hashString, isPathDirectory, } from './lib/apps/index.js';
 import { getGlobIgnorePathsChecker } from './lib/apps/paths.js';
+import { slugFromApp } from './lib/apps/slug.js';
 import { default as localConfig } from './lib/config.js';
 import { toAppId } from './lib/create/index.js';
 import { detectPackageManager, transformCommand, } from './lib/package-manager.js';
@@ -139,7 +140,7 @@ export class PushAppCommand extends RemoteAppCommand {
         }
         const appSlugId = (await select({
             choices: apps.results.map((app) => ({
-                name: `${style.appConfigValue(app.name)} (${getAppSlugId(app)})`,
+                name: `${style.appConfigValue(app.name)} (${slugFromApp(app) ?? app.id})`,
                 value: app.private_id,
             })),
             message: `Choose ${typeLabelPrefixed} to pull`,

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

@@ -1,14 +1,11 @@
 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>;
     protected catch(error: Error): Promise<any>;
     private parseCommand;
-    /**
-     * Resolve app ObjectId from a friendly slug or return as-is if already an ObjectId.
-     */
-    private resolveAppId;
     /**
      * Resolve function ID from app ID and function name.
      */
@@ -18,6 +15,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,12 +1,21 @@
+import { Flags } from '@oclif/core';
 import * as fs from 'node:fs';
 import path from 'node:path';
 import { FetchError } from 'node-fetch';
 import { HttpMethod } from './lib/api.js';
+import { resolveAppId } from './lib/apps/resolve.js';
 import { SwellCommand } from './swell-command.js';
 // Pattern to match /functions/{appId}/{functionName} with optional query string
 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 +38,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 +50,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 }
@@ -68,28 +86,11 @@ export class SwellApiCommand extends SwellCommand {
             },
         };
     }
-    /**
-     * Resolve app ObjectId from a friendly slug or return as-is if already an ObjectId.
-     */
-    async resolveAppId(appIdOrSlug) {
-        // If it looks like an ObjectId (24 hex chars), return as-is
-        if (/^[\da-f]{24}$/i.test(appIdOrSlug)) {
-            return appIdOrSlug;
-        }
-        // Fetch all installed apps and filter by public_id or private_id client-side
-        const installedApps = await this.api.get({ adminPath: `/client/apps` });
-        const app = installedApps?.results?.find((a) => a.app_public_id === appIdOrSlug ||
-            a.app_private_id === `_${appIdOrSlug}`);
-        if (!app) {
-            throw new Error(`App '${appIdOrSlug}' not found`);
-        }
-        return app.app_id;
-    }
     /**
      * Resolve function ID from app ID and function name.
      */
     async resolveFunctionId(appIdOrSlug, functionName) {
-        const appId = await this.resolveAppId(appIdOrSlug);
+        const appId = await resolveAppId(this.api, appIdOrSlug);
         const functionRecord = await this.api.get({ adminPath: `/data/:functions` }, {
             query: {
                 app_id: appId,
@@ -108,27 +109,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 {};