@salesforce/webapp-experimental 0.2.0

package/dist/app/org.js

@@ -0,0 +1,62 @@
+import { Org } from "@salesforce/core";
+/**
+ * Get Salesforce org info and authentication details
+ *
+ * @param orgAlias - Optional org alias or username, uses default org if not provided
+ * @returns Promise resolving to org info or null if authentication fails
+ */
+export async function getOrgInfo(orgAlias) {
+    const org = await createOrg(orgAlias);
+    if (!org) {
+        return;
+    }
+    const connection = org.getConnection();
+    const authInfo = connection.getAuthInfo();
+    const authFields = authInfo.getFields();
+    return {
+        apiVersion: connection.getApiVersion(),
+        orgId: authFields.orgId ?? "",
+        instanceUrl: toLightningDomain(connection.instanceUrl),
+        username: authFields.username ?? "",
+        accessToken: connection.accessToken ?? "",
+        orgAlias,
+    };
+}
+async function createOrg(orgAlias) {
+    try {
+        if (!orgAlias) {
+            return await Org.create({});
+        }
+        return await Org.create({ aliasOrUsername: orgAlias });
+    }
+    catch (error) {
+        console.error("Failed to get SF org info:", error);
+    }
+}
+/**
+ * Refresh Salesforce org authentication
+ *
+ * @param orgAlias
+ */
+export async function refreshOrgAuth(orgAlias) {
+    const org = await Org.create({ aliasOrUsername: orgAlias });
+    await org.refreshAuth();
+    return getOrgInfo(orgAlias);
+}
+function replaceLast(originalString, searchString, replacementString) {
+    const lastIndex = originalString.lastIndexOf(searchString);
+    if (lastIndex === -1) {
+        return originalString;
+    }
+    const before = originalString.slice(0, lastIndex);
+    const after = originalString.slice(lastIndex + searchString.length);
+    return before + replacementString + after;
+}
+function toLightningDomain(instanceUrl) {
+    if (!instanceUrl.includes(".my.")) {
+        return instanceUrl;
+    }
+    let url = replaceLast(instanceUrl, ".my.", ".lightning.");
+    url = replaceLast(url, ".salesforce", ".force");
+    return url;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./api/index.js";
+export * from "./app/index.js";
+export * from "./proxy/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+// Browser-safe API clients
+export * from "./api/index.js";
+export * from "./app/index.js";
+export * from "./proxy/index.js";

package/dist/proxy/handler.d.ts

@@ -0,0 +1,23 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { OrgInfo, WebAppManifest } from "../app/index.js";
+/**
+ * Configuration options for the WebApp proxy handler
+ */
+export interface ProxyOptions {
+    debug?: boolean;
+}
+/**
+ * Proxy handler function type
+ */
+export type ProxyHandler = (req: IncomingMessage, res: ServerResponse, next?: () => void) => Promise<void>;
+/**
+ * Create proxy request handler
+ *
+ * @param manifest - WebApp manifest configuration
+ * @param orgInfo - Salesforce org information
+ * @param target - Target URL for dev server forwarding
+ * @param options - Proxy configuration options
+ * @returns Async request handler function for Node.js HTTP server
+ */
+export declare function createProxyHandler(manifest: WebAppManifest, orgInfo?: OrgInfo, target?: string, basePath?: string, options?: ProxyOptions): ProxyHandler;
+//# sourceMappingURL=handler.d.ts.map

package/dist/proxy/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../src/proxy/handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAG/D;;GAEG;AACH,MAAM,WAAW,YAAY;IAE5B,KAAK,CAAC,EAAE,OAAO,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,CAC1B,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,IAAI,CAAC,EAAE,MAAM,IAAI,KACb,OAAO,CAAC,IAAI,CAAC,CAAC;AA8MnB;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CACjC,QAAQ,EAAE,cAAc,EACxB,OAAO,CAAC,EAAE,OAAO,EACjB,MAAM,CAAC,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,YAAY,GACpB,YAAY,CAGd"}

package/dist/proxy/handler.js

@@ -0,0 +1,210 @@
+import { applyTrailingSlash, matchRoute } from "./routing.js";
+import { refreshOrgAuth } from "../app/index.js";
+/**
+ * Handles all proxy routing and forwarding for WebApps
+ */
+class WebAppProxyHandler {
+    manifest;
+    orgInfo;
+    target;
+    basePath;
+    options;
+    constructor(manifest, orgInfo, target, basePath, options) {
+        this.manifest = manifest;
+        this.orgInfo = orgInfo;
+        this.target = target;
+        this.basePath = basePath;
+        this.options = options;
+    }
+    async handle(req, res, next) {
+        const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+        let pathname = url.pathname;
+        if (this.options?.debug) {
+            console.log(`[webapps-proxy] ${req.method} ${pathname}`);
+        }
+        pathname = applyTrailingSlash(pathname, this.manifest.routing?.trailingSlash);
+        const match = matchRoute(pathname, this.basePath, this.manifest.routing?.rewrites, this.manifest.routing?.redirects);
+        if (match) {
+            if (match.type === "api") {
+                await this.handleSalesforceApi(req, res);
+                return;
+            }
+            if (match.type === "redirect" && match.target && match.statusCode) {
+                this.handleRedirect(res, match.target, match.statusCode);
+                return;
+            }
+            if (match.type === "rewrite" && match.target) {
+                url.pathname = `/${match.target}`.replace(/\/+/g, "/");
+                req.url = url.pathname + url.search;
+                if (this.options?.debug) {
+                    console.log(`[webapps-proxy] Rewrite to ${req.url}`);
+                }
+            }
+        }
+        if (next) {
+            next();
+        }
+        else {
+            await this.forwardToDevServer(req, res);
+        }
+    }
+    handleRedirect(res, location, statusCode) {
+        res.writeHead(statusCode, { Location: location });
+        res.end();
+    }
+    async handleSalesforceApi(req, res) {
+        try {
+            if (!this.orgInfo) {
+                res.writeHead(401, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({
+                    error: "NO_ORG_FOUND",
+                    message: "No default Salesforce org found. Run 'sf org login web --set-default' to authenticate.",
+                }));
+                return;
+            }
+            const url = new URL(req.url ?? "/", `http://${req.headers.host}`);
+            let pathIndex = url.pathname.indexOf("/lwr/apex/v");
+            if (pathIndex === -1) {
+                pathIndex = url.pathname.indexOf("/services/data/v");
+            }
+            const apiPath = url.pathname.substring(pathIndex);
+            let targetUrl = `${this.orgInfo.instanceUrl}${apiPath}${url.search}`;
+            if (this.options?.debug) {
+                console.log(`[webapps-proxy] Forwarding to Salesforce: ${targetUrl}`);
+            }
+            // Buffer the request body before sending. This allows us to retry requests
+            // with the same body in case of authentication failures (403).
+            // For GET/HEAD requests, body is undefined.
+            const body = req.method !== "GET" && req.method !== "HEAD" ? await getBody(req) : undefined;
+            let response = await fetch(targetUrl, {
+                method: req.method,
+                headers: {
+                    ...getFilteredHeaders(req.headers),
+                    Cookie: `sid=${this.orgInfo.accessToken}`,
+                    Accept: req.headers.accept ?? "application/json",
+                    // necessary for Apex requests, for which SessionUtil.validateSessionUsage won't accept OAuth token as `sid` cookie
+                    Authorization: `Bearer ${this.orgInfo.accessToken}`,
+                },
+                body: body,
+            });
+            if (response.status === 401 || response.status === 403) {
+                console.warn(`[webapps-proxy] Received ${response.status}, refreshing token...`);
+                // Use the orgAlias from the current orgInfo to maintain consistency
+                const updatedOrgInfo = await refreshOrgAuth(this.orgInfo.orgAlias);
+                if (!updatedOrgInfo) {
+                    throw new Error("Failed to refresh token");
+                }
+                this.orgInfo = updatedOrgInfo;
+                if (this.orgInfo) {
+                    if (this.options?.debug) {
+                        console.log("[webapps-proxy] Token refreshed, retrying request");
+                    }
+                    // Update target URL with refreshed org info (instance URL may have changed)
+                    targetUrl = `${this.orgInfo.instanceUrl}${url.pathname}${url.search}`;
+                    // Retry with the same buffered body
+                    response = await fetch(targetUrl, {
+                        method: req.method,
+                        headers: {
+                            ...getFilteredHeaders(req.headers),
+                            Cookie: `sid=${this.orgInfo.accessToken}`,
+                            Accept: req.headers.accept ?? "application/json",
+                        },
+                        body: body,
+                    });
+                }
+            }
+            await this.sendResponse(res, response);
+        }
+        catch (error) {
+            console.error("[webapps-proxy] Salesforce API request failed:", error);
+            res.writeHead(502, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                error: "GATEWAY_ERROR",
+                message: "Failed to forward request to Salesforce",
+            }));
+        }
+    }
+    async forwardToDevServer(req, res) {
+        try {
+            const url = new URL(req.url ?? "/", this.target);
+            if (this.options?.debug) {
+                console.log(`[webapps-proxy] Forwarding to dev server: ${url.href}`);
+            }
+            const body = req.method !== "GET" && req.method !== "HEAD" ? await getBody(req) : undefined;
+            const response = await fetch(url.href, {
+                method: req.method,
+                headers: getFilteredHeaders(req.headers),
+                body: body,
+            });
+            await this.sendResponse(res, response);
+        }
+        catch (error) {
+            console.error("[webapps-proxy] Dev server request failed:", error);
+            res.writeHead(502, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                error: "GATEWAY_ERROR",
+                message: "Failed to forward request to dev server",
+            }));
+        }
+    }
+    async sendResponse(res, response) {
+        const headers = {};
+        const skipHeaders = new Set(["content-encoding", "content-length", "transfer-encoding"]);
+        response.headers.forEach((value, key) => {
+            if (!skipHeaders.has(key.toLowerCase())) {
+                headers[key] = value;
+            }
+        });
+        res.writeHead(response.status, headers);
+        if (response.body) {
+            const reader = response.body.getReader();
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                res.write(value);
+            }
+        }
+        res.end();
+    }
+}
+/**
+ * Create proxy request handler
+ *
+ * @param manifest - WebApp manifest configuration
+ * @param orgInfo - Salesforce org information
+ * @param target - Target URL for dev server forwarding
+ * @param options - Proxy configuration options
+ * @returns Async request handler function for Node.js HTTP server
+ */
+export function createProxyHandler(manifest, orgInfo, target, basePath, options) {
+    const handler = new WebAppProxyHandler(manifest, orgInfo, target, basePath, options);
+    return (req, res, next) => handler.handle(req, res, next);
+}
+function getFilteredHeaders(headers) {
+    const filtered = {};
+    const hopByHopHeaders = new Set([
+        "connection",
+        "keep-alive",
+        "proxy-authenticate",
+        "proxy-authorization",
+        "te",
+        "trailer",
+        "transfer-encoding",
+        "upgrade",
+    ]);
+    for (const [key, value] of Object.entries(headers)) {
+        if (!hopByHopHeaders.has(key.toLowerCase()) && value) {
+            filtered[key] = Array.isArray(value) ? value.join(", ") : value;
+        }
+    }
+    return filtered;
+}
+function getBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on("data", (chunk) => chunks.push(chunk));
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}

package/dist/proxy/index.d.ts

@@ -0,0 +1,3 @@
+export type { ProxyOptions, ProxyHandler } from "./handler.js";
+export { createProxyHandler } from "./handler.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/proxy/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/proxy/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}

package/dist/proxy/index.js

@@ -0,0 +1 @@
+export { createProxyHandler } from "./handler.js";

package/dist/proxy/routing.d.ts

@@ -0,0 +1,34 @@
+import type { RedirectRule, RewriteRule } from "../app/index.js";
+export interface RouteMatch {
+    type: "rewrite" | "redirect" | "api";
+    target?: string;
+    statusCode?: number;
+    params?: Record<string, string>;
+}
+/**
+ * Match URL path against routing rules
+ *
+ * @param pathname - The URL pathname to match
+ * @param rewrites - Optional array of rewrite rules
+ * @param redirects - Optional array of redirect rules
+ * @returns Route match result indicating the type and target, or null if no match
+ */
+export declare function matchRoute(pathname: string, basePath?: string, rewrites?: RewriteRule[], redirects?: RedirectRule[]): RouteMatch | null;
+/**
+ * Check if a path matches any of the given glob patterns
+ * Supports glob wildcards: * (matches anything except /), ** (matches anything including /), ? (single character)
+ *
+ * @param path - The path to test
+ * @param patterns - Array of glob patterns to match against
+ * @returns True if the path matches any pattern, false otherwise
+ */
+export declare function matchesPattern(path: string, patterns: string[] | undefined): boolean;
+/**
+ * Apply trailing slash rules to pathname
+ *
+ * @param pathname - The URL pathname
+ * @param trailingSlash - Trailing slash handling strategy
+ * @returns Modified pathname with trailing slash applied according to rules
+ */
+export declare function applyTrailingSlash(pathname: string, trailingSlash?: "always" | "never" | "auto"): string;
+//# sourceMappingURL=routing.d.ts.map

package/dist/proxy/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../src/proxy/routing.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEjE,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,SAAS,GAAG,UAAU,GAAG,KAAK,CAAC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AASD;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACzB,QAAQ,EAAE,MAAM,EAChB,QAAQ,CAAC,EAAE,MAAM,EACjB,QAAQ,CAAC,EAAE,WAAW,EAAE,EACxB,SAAS,CAAC,EAAE,YAAY,EAAE,GACxB,UAAU,GAAG,IAAI,CA2DnB;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,OAAO,CAMpF;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CACjC,QAAQ,EAAE,MAAM,EAChB,aAAa,CAAC,EAAE,QAAQ,GAAG,OAAO,GAAG,MAAM,GACzC,MAAM,CAiBR"}

package/dist/proxy/routing.js

@@ -0,0 +1,100 @@
+import micromatch from "micromatch";
+import { match } from "path-to-regexp";
+function normalizeRoute(route) {
+    let wildcardIndex = 0;
+    return route.replace(/\*/g, () => {
+        return `{*wildcard${wildcardIndex++}}`;
+    });
+}
+/**
+ * Match URL path against routing rules
+ *
+ * @param pathname - The URL pathname to match
+ * @param rewrites - Optional array of rewrite rules
+ * @param redirects - Optional array of redirect rules
+ * @returns Route match result indicating the type and target, or null if no match
+ */
+export function matchRoute(pathname, basePath, rewrites, redirects) {
+    if (pathname.startsWith(`${basePath || ""}/services/data/v`) ||
+        pathname.startsWith(`${basePath || ""}/lwr/apex/v`)) {
+        return { type: "api" };
+    }
+    if (redirects) {
+        for (const redirect of redirects) {
+            const normalizedRoute = normalizeRoute(redirect.route);
+            const matcher = match(normalizedRoute, { decode: decodeURIComponent });
+            const result = matcher(pathname);
+            if (result) {
+                let target = redirect.target;
+                const params = result.params;
+                for (const [key, value] of Object.entries(params)) {
+                    if (!key.startsWith("wildcard")) {
+                        target = target.replace(`:${key}`, value);
+                    }
+                }
+                return {
+                    type: "redirect",
+                    target,
+                    statusCode: redirect.statusCode,
+                };
+            }
+        }
+    }
+    if (rewrites) {
+        for (const rewrite of rewrites) {
+            const normalizedRoute = normalizeRoute(rewrite.route);
+            const matcher = match(normalizedRoute, { decode: decodeURIComponent });
+            const result = matcher(pathname);
+            if (result) {
+                const params = {};
+                const matchParams = result.params;
+                for (const [key, value] of Object.entries(matchParams)) {
+                    if (!key.startsWith("wildcard")) {
+                        params[key] = value;
+                    }
+                }
+                return {
+                    type: "rewrite",
+                    target: rewrite.target,
+                    params,
+                };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Check if a path matches any of the given glob patterns
+ * Supports glob wildcards: * (matches anything except /), ** (matches anything including /), ? (single character)
+ *
+ * @param path - The path to test
+ * @param patterns - Array of glob patterns to match against
+ * @returns True if the path matches any pattern, false otherwise
+ */
+export function matchesPattern(path, patterns) {
+    if (!patterns || patterns.length === 0) {
+        return false;
+    }
+    return micromatch.isMatch(path, patterns);
+}
+/**
+ * Apply trailing slash rules to pathname
+ *
+ * @param pathname - The URL pathname
+ * @param trailingSlash - Trailing slash handling strategy
+ * @returns Modified pathname with trailing slash applied according to rules
+ */
+export function applyTrailingSlash(pathname, trailingSlash) {
+    if (!trailingSlash || trailingSlash === "auto") {
+        return pathname;
+    }
+    const hasTrailingSlash = pathname.endsWith("/");
+    const isRoot = pathname === "/";
+    if (trailingSlash === "always" && !hasTrailingSlash && !isRoot) {
+        return `${pathname}/`;
+    }
+    if (trailingSlash === "never" && hasTrailingSlash && !isRoot) {
+        return pathname.slice(0, -1);
+    }
+    return pathname;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@salesforce/webapp-experimental",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./api": {
+      "types": "./dist/api/index.d.ts",
+      "import": "./dist/api/index.js"
+    },
+    "./app": {
+      "types": "./dist/app/index.d.ts",
+      "import": "./dist/app/index.js"
+    },
+    "./proxy": {
+      "types": "./dist/proxy/index.d.ts",
+      "import": "./dist/proxy/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc --build",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "dev": "tsc --build --watch"
+  },
+  "dependencies": {
+    "@conduit-client/salesforce-lightning-service-worker": "^3.7.0",
+    "@salesforce/core": "^8.23.4",
+    "axios": "^1.7.7",
+    "micromatch": "^4.0.8",
+    "path-to-regexp": "^8.3.0"
+  },
+  "devDependencies": {
+    "@types/micromatch": "^4.0.10",
+    "vitest": "^4.0.6"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "gitHead": "a806910fe9c132ad3cc0ca63302072b0076699b9"
+}