@swell/cli 2.2.0 → 2.3.0

package/dist/lib/create/tests/templates/vitest-config.js

@@ -0,0 +1,122 @@
+export function vitestConfigTemplate(options) {
+    return `\
+import { defineWorkersConfig } from "@cloudflare/vitest-pool-workers/config";
+import { readFileSync, existsSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+type SdkAuth = {
+  storeId: string;
+  sessionId: string;
+  apiBaseUrl: string;
+};
+
+const isCI = Boolean(process.env.CI || process.env.CONTINUOUS_INTEGRATION);
+
+function loadSwellAuth(): SdkAuth {
+  const envStoreId = process.env.SWELL_STORE_ID;
+  const envSessionId = process.env.SWELL_SESSION_ID;
+  const envApiBaseUrl = process.env.SWELL_API_BASE_URL;
+
+  if (envStoreId && envSessionId) {
+    return {
+      storeId: envStoreId,
+      sessionId: envSessionId,
+      apiBaseUrl: envApiBaseUrl || \`https://\${envStoreId}.swell.store/admin/api\`,
+    };
+  }
+
+  if (isCI) {
+    throw new Error(
+      "CI environment detected but SWELL_STORE_ID and SWELL_SESSION_ID are not set. " +
+        "Add these as CI secrets/variables to run integration tests.",
+    );
+  }
+
+  const home = homedir();
+  const configPath = path.resolve(home, ".swell", "config.json");
+  if (!existsSync(configPath)) {
+    throw new Error(
+      \`Swell CLI config not found at \${configPath}. Run \\\`swell login\\\` or set SWELL_STORE_ID and SWELL_SESSION_ID.\`
+    );
+  }
+
+  const rawConfig = readFileSync(configPath, "utf-8");
+
+  interface CliConfig {
+    defaultStore?: string;
+    stores?: { storeId: string; sessionId?: string }[];
+  }
+
+  let configJson: CliConfig;
+
+  try {
+    configJson = JSON.parse(rawConfig) as CliConfig;
+  } catch (error) {
+    throw new Error(
+      \`Unable to parse Swell CLI config at \${configPath}: \${String(error)}\`
+    );
+  }
+
+  const defaultStore = configJson.defaultStore;
+  const stores = configJson.stores || [];
+
+  const store = defaultStore
+    ? stores.find((item) => item.storeId === defaultStore)
+    : undefined;
+
+  if (!defaultStore || !store?.sessionId) {
+    throw new Error(
+      "No active Swell CLI session found. Run \\\`swell login\\\` or set SWELL_STORE_ID and SWELL_SESSION_ID.",
+    );
+  }
+
+  const envPath = path.join(home, ".swell", "env.json");
+  let apiBaseUrl = \`https://\${defaultStore}.swell.store/admin/api\`;
+
+  if (existsSync(envPath)) {
+    try {
+      const rawEnv = readFileSync(envPath, "utf-8");
+      const envJson = JSON.parse(rawEnv) as { ADMIN_API_BASE_URL?: string };
+      if (envJson.ADMIN_API_BASE_URL) {
+        apiBaseUrl = envJson.ADMIN_API_BASE_URL.replace("\${STORE_ID}", defaultStore);
+      }
+    } catch {
+      // Ignore env parsing errors and fall back to default
+    }
+  }
+
+  return {
+    storeId: defaultStore,
+    sessionId: store.sessionId!,
+    apiBaseUrl,
+  };
+}
+
+const sdkAuth = loadSwellAuth();
+
+export default defineWorkersConfig({
+  test: {
+    globals: true,
+    include: ["test/**/*.test.ts"],
+    exclude: ["node_modules", "docs"],
+    setupFiles: ["./test/setup-globals.ts"],
+    poolOptions: {
+      workers: {
+        singleWorker: true,
+        isolatedStorage: true,
+        miniflare: {
+          bindings: {
+            SWELL_STORE_ID: sdkAuth.storeId,
+            SWELL_SESSION_ID: sdkAuth.sessionId,
+            SWELL_API_BASE_URL: sdkAuth.apiBaseUrl,
+            SWELL_APP_ID: "${options.appId}",
+            SWELL_ENVIRONMENT: "test",
+          },
+        },
+      },
+    },
+  },
+});
+`;
+}

package/dist/lib/create/tests/types.d.ts

@@ -0,0 +1,21 @@
+interface TestTemplateOptions {
+    /** App id from swell.json, used for SWELL_APP_ID and settings() */
+    appId: string;
+}
+interface WriteTestsOptions extends TestTemplateOptions {
+    /** Absolute path to the app root */
+    appPath: string;
+    /** Overwrite existing files if present */
+    overwrite: boolean;
+}
+interface ScaffoldResult {
+    /** Files that were created or overwritten */
+    createdFiles: string[];
+    /** Files that were skipped because they already exist */
+    skippedFiles: string[];
+    /** Whether package.json was updated */
+    packageJsonUpdated: boolean;
+    /** Warning messages to display to user */
+    warnings: string[];
+}
+export type { ScaffoldResult, TestTemplateOptions, WriteTestsOptions };

package/dist/lib/create/tests/types.js

@@ -0,0 +1 @@
+export {};

package/dist/lib/create/tests.d.ts

@@ -0,0 +1,4 @@
+import type { ScaffoldResult, WriteTestsOptions } from './tests/types.js';
+declare function createTestsScaffold(options: WriteTestsOptions): Promise<ScaffoldResult>;
+export { createTestsScaffold };
+export type { ScaffoldResult } from './tests/types.js';

package/dist/lib/create/tests.js

@@ -0,0 +1,113 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { filePathExists, writeFile } from '../apps/index.js';
+import { envDtsTemplate, integrationTestTemplate, mockRequestTemplate, setupGlobalsTemplate, swellClientTemplate, tsconfigTemplate, unitTestTemplate, vitestConfigTemplate, } from './tests/templates/index.js';
+const TEST_DEV_DEPENDENCIES = {
+    '@cloudflare/vitest-pool-workers': 'latest',
+    vitest: 'latest',
+    '@swell/app-types': 'latest',
+};
+async function writeTextFile(filePath, contents, overwrite) {
+    if (!overwrite && filePathExists(filePath)) {
+        return { created: false, skipped: true };
+    }
+    await writeFile(filePath, contents);
+    return { created: true, skipped: false };
+}
+function updatePackageJson(appPath) {
+    const pkgPath = path.join(appPath, 'package.json');
+    if (!filePathExists(pkgPath)) {
+        return {
+            updated: false,
+            warning: 'package.json not found. Run `npm init` first.',
+        };
+    }
+    let pkgRaw;
+    try {
+        pkgRaw = fs.readFileSync(pkgPath, 'utf8');
+    }
+    catch (error) {
+        return {
+            updated: false,
+            warning: `Could not read package.json: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    let pkg;
+    try {
+        pkg = JSON.parse(pkgRaw);
+    }
+    catch (error) {
+        return {
+            updated: false,
+            warning: `Could not parse package.json: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    const devDeps = (pkg.devDependencies || {});
+    const deps = (pkg.dependencies || {});
+    devDeps['@cloudflare/vitest-pool-workers'] =
+        devDeps['@cloudflare/vitest-pool-workers'] ||
+            TEST_DEV_DEPENDENCIES['@cloudflare/vitest-pool-workers'];
+    devDeps.vitest = devDeps.vitest || TEST_DEV_DEPENDENCIES.vitest;
+    if (!devDeps['@swell/app-types'] && !deps['@swell/app-types']) {
+        devDeps['@swell/app-types'] = TEST_DEV_DEPENDENCIES['@swell/app-types'];
+    }
+    pkg.devDependencies = devDeps;
+    const scripts = (pkg.scripts || {});
+    scripts.test = scripts.test || 'vitest run';
+    pkg.scripts = scripts;
+    try {
+        const next = `${JSON.stringify(pkg, null, 2)}\n`;
+        fs.writeFileSync(pkgPath, next, 'utf8');
+        return { updated: true };
+    }
+    catch (error) {
+        return {
+            updated: false,
+            warning: `Could not write package.json: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+function validatePrerequisites(appPath) {
+    const warnings = [];
+    const tsconfigPath = path.join(appPath, 'tsconfig.json');
+    if (!filePathExists(tsconfigPath)) {
+        warnings.push('tsconfig.json not found. test/tsconfig.json extends it; create one or tests may not compile.');
+    }
+    return warnings;
+}
+async function createTestsScaffold(options) {
+    const { appPath, appId, overwrite } = options;
+    const result = {
+        createdFiles: [],
+        skippedFiles: [],
+        packageJsonUpdated: false,
+        warnings: [],
+    };
+    const prereqWarnings = validatePrerequisites(appPath);
+    result.warnings.push(...prereqWarnings);
+    const trackFile = async (relativePath, contents) => {
+        const fullPath = path.join(appPath, relativePath);
+        const writeResult = await writeTextFile(fullPath, contents, overwrite);
+        if (writeResult.created) {
+            result.createdFiles.push(relativePath);
+        }
+        else if (writeResult.skipped) {
+            result.skippedFiles.push(relativePath);
+        }
+    };
+    await trackFile('vitest.config.ts', vitestConfigTemplate({ appId }));
+    await trackFile('test/tsconfig.json', tsconfigTemplate());
+    await trackFile('test/env.d.ts', envDtsTemplate());
+    await trackFile('test/setup-globals.ts', setupGlobalsTemplate());
+    await trackFile('test/helpers/swell-client.ts', swellClientTemplate());
+    await trackFile('test/helpers/mock-request.ts', mockRequestTemplate({ appId }));
+    await trackFile('test/unit/example.test.ts', unitTestTemplate());
+    await trackFile('test/integration/example.test.ts', integrationTestTemplate());
+    const pkgResult = updatePackageJson(appPath);
+    result.packageJsonUpdated = pkgResult.updated;
+    if (pkgResult.warning) {
+        result.warnings.push(pkgResult.warning);
+    }
+    return result;
+}
+export { createTestsScaffold };

package/dist/lib/create/webhook.d.ts

@@ -0,0 +1,32 @@
+interface CreateWebhookFileBody {
+    $schema: string;
+    description?: string;
+    enabled?: boolean;
+    events: string[];
+    url: string;
+}
+type ErrorHandler = (msg: string, options: {
+    exit: number;
+}) => never;
+/**
+ * Parse comma-separated events string to array
+ * Input: "payment.succeeded,payment.failed"
+ * Output: ["payment.succeeded", "payment.failed"]
+ */
+declare const parseEvents: (eventsInput: string) => string[];
+/**
+ * Validate event format (model.action pattern)
+ * Valid: "product.created", "payment.succeeded"
+ * Invalid: "product", "created", "", ".created", "product."
+ */
+declare const validateEventFormat: (events: string[], onError: ErrorHandler) => void;
+/**
+ * Validate URL format (basic check for protocol)
+ */
+declare const validateUrl: (url: string, onError: ErrorHandler) => void;
+/**
+ * Convert name to webhook label
+ * "payment-handler" => "Payment Handler"
+ */
+declare const toWebhookLabel: (value: string) => string;
+export { CreateWebhookFileBody, parseEvents, toWebhookLabel, validateEventFormat, validateUrl, };

package/dist/lib/create/webhook.js

@@ -0,0 +1,52 @@
+import { titleize } from 'inflection';
+/**
+ * Parse comma-separated events string to array
+ * Input: "payment.succeeded,payment.failed"
+ * Output: ["payment.succeeded", "payment.failed"]
+ */
+const parseEvents = (eventsInput) => {
+    if (!eventsInput) {
+        return [];
+    }
+    return eventsInput
+        .split(',')
+        .map((e) => e.trim())
+        .filter(Boolean);
+};
+/**
+ * Validate event format (model.action pattern)
+ * Valid: "product.created", "payment.succeeded"
+ * Invalid: "product", "created", "", ".created", "product."
+ */
+const validateEventFormat = (events, onError) => {
+    const invalid = [];
+    for (const event of events) {
+        const parts = event.split('.');
+        if (parts.length !== 2 || !parts[0] || !parts[1]) {
+            invalid.push(event);
+        }
+    }
+    if (invalid.length > 0) {
+        onError(`Invalid event format: ${invalid.join(', ')}\n\nEvents must follow the 'model.action' pattern (e.g., product.created, payment.succeeded).\n\nExample: swell create webhook my-hook -u https://example.com -e order.created,order.updated -y`, { exit: 1 });
+    }
+};
+/**
+ * Validate URL format (basic check for protocol)
+ */
+const validateUrl = (url, onError) => {
+    try {
+        const parsed = new URL(url);
+        if (!['http:', 'https:'].includes(parsed.protocol)) {
+            throw new Error('Invalid protocol');
+        }
+    }
+    catch {
+        onError(`Invalid URL format: ${url}\n\nURL must be a valid HTTP or HTTPS endpoint.\n\nExample: swell create webhook my-hook -u https://example.com/webhook -e order.created -y`, { exit: 1 });
+    }
+};
+/**
+ * Convert name to webhook label
+ * "payment-handler" => "Payment Handler"
+ */
+const toWebhookLabel = (value) => titleize(value).replaceAll('-', ' ');
+export { parseEvents, toWebhookLabel, validateEventFormat, validateUrl, };

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

@@ -5,6 +5,20 @@ export declare abstract class SwellApiCommand extends SwellCommand {
     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.
+     */
+    private resolveFunctionId;
+    private isPlainObject;
+    /**
+     * Build a function invocation request via the admin /:functions endpoint.
+     */
+    private buildFunctionCallRequest;
+    private parseQueryString;
     private processBody;
     private isFilePath;
     private handleResponse;

package/dist/swell-api-command.js

@@ -1,11 +1,17 @@
 import * as fs from 'node:fs';
 import path from 'node:path';
 import { FetchError } from 'node-fetch';
+import { HttpMethod } from './lib/api.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\/([^/?]+)(\?.*)?$/;
 export class SwellApiCommand extends SwellCommand {
     async request(command, requestOptions = {}) {
-        const { paths, options } = await this.parseCommand(command);
-        const response = await this.api[this.method](paths, {
+        const { paths, options, methodOverride } = await this.parseCommand(command);
+        const method = methodOverride || this.method;
+        const response = await this.api[method](paths, {
             rawResponse: true,
             ...options,
             ...requestOptions,
@@ -22,22 +28,112 @@ export class SwellApiCommand extends SwellCommand {
     async parseCommand(options, argv) {
         const parsedInput = await super.parse(options, argv);
         const { args, flags } = parsedInput;
-        const { path } = args;
+        const { path: requestPath } = args;
         const { live, body } = flags;
         if (!live) {
             await this.api.setEnv('test');
         }
-        if (!path.startsWith('/')) {
+        if (!requestPath.startsWith('/')) {
             throw new Error('Path must start with a forward slash (/)');
         }
+        const processedBody = await this.processBody(body);
+        // 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);
+        }
+        // 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);
+        }
+        const paths = { adminPath: `/data${requestPath}` };
         return {
             ...parsedInput,
-            paths: { adminPath: `/data${path}` },
+            paths,
             options: {
-                body: await this.processBody(body),
+                body: processedBody,
             },
         };
     }
+    /**
+     * 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 functionRecord = await this.api.get({ adminPath: `/data/:functions` }, {
+            query: {
+                app_id: appId,
+                name: functionName,
+                limit: 1,
+            },
+        });
+        if (!functionRecord?.results?.length) {
+            throw new Error(`Function '${functionName}' not found for app '${appIdOrSlug}'`);
+        }
+        return functionRecord.results[0].id;
+    }
+    isPlainObject(value) {
+        return typeof value === 'object' && value !== null && !Array.isArray(value);
+    }
+    /**
+     * Build a function invocation request via the admin /:functions endpoint.
+     */
+    buildFunctionCallRequest(parsedInput, functionId, bodyData, queryParams) {
+        // 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,
+            },
+        };
+        return {
+            ...parsedInput,
+            paths: { adminPath: `/data/:functions/${functionId}` },
+            options: {
+                body: callBody,
+            },
+            methodOverride: HttpMethod.PUT,
+        };
+    }
+    parseQueryString(queryString) {
+        if (!queryString) {
+            return {};
+        }
+        const params = new URLSearchParams(queryString.slice(1)); // Remove leading '?'
+        const result = {};
+        for (const [key, value] of params.entries()) {
+            result[key] = value;
+        }
+        return result;
+    }
     async processBody(body) {
         if (!body) {
             return;
@@ -54,10 +150,20 @@ export class SwellApiCommand extends SwellCommand {
     }
     async handleResponse(response) {
         const responseText = await response.text();
-        if (responseText.length <= 2) {
+        // Handle truly empty responses (no body) - success for 2xx status codes
+        // This handles DELETE 204 No Content and similar cases
+        if (!responseText) {
+            if (response.ok) {
+                this.onSuccess({ success: true });
+                return;
+            }
             throw new Error('Not found');
         }
         const result = JSON.parse(responseText);
+        // API returned empty/null content in body - this is "not found" semantics
+        if (result === null || result === undefined || result === '') {
+            throw new Error('Not found');
+        }
         if (result.error || result.errors || !response.ok) {
             throw new Error(responseText);
         }