@adobe/alloy-node 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,169 @@
+# @adobe/alloy-node
+
+> [!WARNING]
+> **Alpha. Only `configure`, `sendEvent`, Identity's commands, Consent, a
+> minimal Context, and fetch-only Personalization are exercised so far.**
+> Most other optional components (Audiences, RulesEngine, etc.) are not
+> wired up yet.
+
+Node.js entrypoint for the Adobe Experience Platform Web SDK.
+
+```js
+import { createInstance } from "@adobe/alloy-node";
+
+const alloy = createInstance();
+await alloy.configure({
+  orgId: "...",
+  datastreamId: "...",
+});
+await alloy.sendEvent({ xdm: { eventType: "..." } });
+```
+
+Unlike the browser bundle's `alloy("commandName", options)` calling
+convention, `createInstance`/`createCustomInstance` return an object with
+real methods (`configure`, `sendEvent`, `getIdentity`,
+`appendIdentityToUrl`, `applyResponse`, `getLibraryInfo`, `setDebug`,
+`setConsent`). The browser bundle uses a callable string-command dispatcher
+so a synchronous stub can queue calls before the library finishes loading
+asynchronously — that doesn't apply in Node, so methods are used instead for
+discoverability.
+
+## One instance per process, `forRequest()` per request
+
+Call `configure()` once, when your server starts — the same way you'd
+configure once per page load in the browser. Node has no equivalent of a
+page load resetting everything between visitors, though, so a real server
+needs a way to resolve _this request's_ visitor identity without recreating
+or reconfiguring the whole instance. That's what `forRequest()` is for:
+
+```js
+const alloy = createInstance();
+await alloy.configure({ orgId: "...", datastreamId: "..." });
+
+// Per request:
+app.get("/", async (req, res) => {
+  const request = alloy.forRequest({
+    cookie: createCookieServiceForThisRequest(req, res),
+  });
+  const result = await request.sendEvent({ xdm: { eventType: "..." } });
+  // ...
+});
+```
+
+`forRequest()` returns a bound handle with the same methods (minus
+`configure`, since it's already configured) backed by its own instance,
+reconfigured under the hood with the same config plus your request-scoped
+`cookie` override. Two requests that share a cookie store (i.e. the same
+visitor, cookies read from their real `Cookie` header) resolve to the same
+identity; requests that don't share one get independent identities — no
+server-side session cache required, since the continuity lives in the
+cookie itself, the same way it already does across browser page loads.
+
+## Hybrid personalization
+
+`createInstance()` includes a fetch-only Personalization component: pass
+`decisionScopes` or `personalization.surfaces`/`personalization.decisionScopes`
+to `sendEvent()` and the result includes a `propositions` array — the same
+shape the browser SDK's `applyPropositions` command expects:
+
+```js
+const { propositions } = await request.sendEvent({
+  xdm: { eventType: "decisioning.propositionFetch" },
+  personalization: { surfaces: ["web://example.com/"] },
+});
+// Serialize `propositions` into the page, then client-side:
+// alloy("applyPropositions", { propositions });
+```
+
+There's no rendering here — no DOM actions, view cache, click tracking, or
+display-notification batching, since there's no page to render into in
+Node. That's the client's job once it calls `applyPropositions`; use
+`createCustomInstance({ components: [] })` to omit this component entirely.
+
+## Consent
+
+`createInstance()` includes Consent, so `setConsent` is available the same
+way it is in the browser — call it per-request, on the `forRequest()` handle,
+with whatever consent value the visitor already recorded in their browser:
+
+```js
+await request.setConsent({
+  consent: [{ standard: "Adobe", version: "1.0", value: { general: "in" } }],
+});
+```
+
+Like identity, consent state is tied to the visitor's cookies (read/written
+through `platformServices.cookie`), so it's automatically scoped correctly
+by whatever `cookie` override you already pass to `forRequest()` — no
+separate wiring needed. If you build a custom instance with
+`createCustomInstance({ components: [...] })` and leave `consent` out,
+`setConsent` will still exist as a method but will reject when called, the
+same as calling an unregistered command in the browser bundle.
+
+## Context
+
+A minimal, always-on Context component attaches `implementationDetails` to
+every event automatically. There's no DOM to read device/viewport/timezone
+info from like the browser version does, but if you pass the real incoming
+request to `forRequest({ request })`, Context also derives
+`web.webPageDetails.URL` from its `Referer` header, and the visitor's real
+headers (`User-Agent`, client hints, `X-Forwarded-For`, etc. — see
+`pickForwardableHeaders`) get forwarded upstream to Edge Network, so its own
+server-side device/locale/geo parsing has real data to work with instead of
+whatever Node's own `fetch()` would send by default:
+
+```js
+const request = alloy.forRequest({
+  cookie: createCookieServiceForThisRequest(req, res),
+  request: req, // any { headers } object — a raw request, Express req, etc.
+});
+```
+
+Everything else the browser's Context collects (screen size, viewport,
+local timezone) has no honest server-side source and isn't guessed at here —
+merge real values directly via `sendEvent({ xdm: { ... } })` if you have
+them.
+
+## Platform services
+
+Both `createInstance(options)` and `forRequest(overrides)` accept a
+`platformServices`-shaped object (flat on `forRequest`, nested under
+`platformServices` on `createInstance`) to override any of the default
+in-memory Node services (`network`, `storage`, `cookie`, `runtime`,
+`legacy`, `globals`) with your own implementation:
+
+```js
+const alloy = createInstance({
+  platformServices: {
+    cookie: createDefaultCookieService(),
+  },
+});
+```
+
+`cookie` is the one you'll reach for most — the default is an in-memory jar,
+so identity resets whenever it's the only thing available (e.g. on the
+top-level instance, if you never call `forRequest()`). Overrides must
+implement the `CookieService` interface (`get`, `getAll`, `set`, `remove`,
+`withConverter`) documented in `@adobe/alloy-core/services`.
+
+### What's visitor-scoped vs. process-scoped
+
+Everything ECID/identity-related — the `kndctr_`/`AMCV_` cookies, edge
+cluster/location-hint affinity, consent cookies forwarded to the Edge
+Network — goes through `cookie`, so it's already correctly bucketed by
+`forRequest()`'s per-request override. `request` (the real incoming HTTP
+request, see [Context](#context)) is inherently per-request too, and is
+never inherited from the top-level instance the way `cookie`/`storage`
+aren't. `storage`'s current uses (debug-flag
+persistence, an Assurance validation client ID) are process-level
+bookkeeping, not visitor state, _except_ that Assurance client ID: it's
+meant to be a stable per-visitor value, but with the default in-memory
+`storage` it resets every request unless you also pass a `storage` override
+to `forRequest()`, the same way you would `cookie`.
+
+If a future component needs to persist visitor-scoped state beyond a single
+request (e.g. decisioning event history for content-card/frequency-capping
+dedup, à la the browser's `personalizationStorageEnabled` — not implemented
+in Node yet), it should read/write that through `platformServices.storage`
+and rely on the same `forRequest({ storage: ... })` override mechanism,
+not a new one.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@adobe/alloy-node",
+  "version": "0.1.0-beta.1",
+  "description": "Adobe Experience Platform Web SDK - Node.js entrypoint",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adobe/alloy.git",
+    "directory": "packages/node"
+  },
+  "author": "Adobe Inc.",
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./src/index.js",
+      "default": "./src/index.js"
+    }
+  },
+  "dependencies": {
+    "@adobe/alloy-core": "^1.2.3-beta.2"
+  },
+  "scripts": {
+    "typecheck": "tsc -p jsconfig.json"
+  }
+}

package/src/allOptionalComponents.js

@@ -0,0 +1,17 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+// This file contains the optional components that can be included in a Node
+// build. Mirrors the shape of packages/browser/src/allOptionalComponents.js.
+
+export { default as personalization } from "./components/personalization.js";
+export { consent } from "@adobe/alloy-core";

package/src/alloy-core.d.ts

@@ -0,0 +1,12 @@
+// placeholder until @adobe/alloy-core passes a typecheck.
+declare module "@adobe/alloy-core" {
+  export function createCustomInstance(
+    options: Record<string, unknown>,
+    createPlatformServices?: () => unknown,
+    coreConfigValidators?: unknown,
+  ): (commandName: string, options?: Record<string, unknown>) => Promise<any>;
+
+  export function createCoreConfigs(): unknown;
+
+  export function consent(options: Record<string, unknown>): unknown;
+}

package/src/components/context.js

@@ -0,0 +1,56 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/** @import { NodeRequestLike } from "../services/createNodePlatformServices.js" */
+
+import packageJson from "../../package.json" with { type: "json" };
+import getHeader from "../services/getHeader.js";
+
+const LIBRARY_NAME = "https://ns.adobe.com/experience/alloy";
+const { version: LIBRARY_VERSION } = packageJson;
+
+/**
+ * Node's analog to the browser bundle's Context component. No DOM to read
+ * device/viewport/timezone from, so this only attaches `implementationDetails`
+ * and, best-effort, `web.webPageDetails.URL` from the `Referer` header of
+ * `forRequest({ request })`.
+ *
+ * @param {Object} params
+ * @param {{ request?: NodeRequestLike }} params.platformServices
+ */
+const createContext = ({ platformServices }) => ({
+  lifecycle: {
+    /** @param {{ event: any }} params */
+    onBeforeEvent({ event }) {
+      event.mergeXdm({
+        implementationDetails: {
+          name: LIBRARY_NAME,
+          version: LIBRARY_VERSION,
+          environment: "server",
+        },
+      });
+
+      const referer = getHeader(platformServices.request?.headers, "referer");
+      if (typeof referer === "string" && referer) {
+        event.mergeXdm({
+          web: { webPageDetails: { URL: referer } },
+        });
+      }
+
+      return Promise.resolve();
+    },
+  },
+});
+
+createContext.namespace = "Context";
+
+export default createContext;

package/src/components/personalization.js

@@ -0,0 +1,99 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+import {
+  DEFAULT_CONTENT_ITEM,
+  DOM_ACTION,
+  HTML_CONTENT_ITEM,
+  JSON_CONTENT_ITEM,
+  REDIRECT_ITEM,
+  RULESET_ITEM,
+  MESSAGE_IN_APP,
+  MESSAGE_CONTENT_CARD,
+} from "@adobe/alloy-core/constants/schema.js";
+
+const DECISIONS_HANDLE = "personalization:decisions";
+
+// Every schema `applyPropositions` (client-side) knows how to process.
+// Unlike the browser component, there's no page-wide scope to conditionally
+// gate DOM_ACTION on — Node has no page, so it's always requested.
+const SCHEMAS = [
+  DEFAULT_CONTENT_ITEM,
+  HTML_CONTENT_ITEM,
+  JSON_CONTENT_ITEM,
+  REDIRECT_ITEM,
+  RULESET_ITEM,
+  MESSAGE_IN_APP,
+  MESSAGE_CONTENT_CARD,
+  DOM_ACTION,
+];
+
+/** @param {Array<string>} array */
+const dedupe = (array) =>
+  array.filter((item, pos) => array.indexOf(item) === pos);
+
+/**
+ * Fetch-only personalization for Node: requests decisions for
+ * `decisionScopes`/`personalization.surfaces`/`personalization.decisionScopes`
+ * passed to `sendEvent`, and returns the raw `personalization:decisions`
+ * payloads as `propositions` — the same shape the browser SDK's
+ * `applyPropositions` command expects, so a server can hand them to a
+ * client to render.
+ *
+ * Deliberately does not include any of the browser Personalization
+ * component's rendering machinery (DOM actions, view cache, click
+ * tracking, display-notification batching, default page-wide scope) —
+ * there's no page or DOM in Node to render into or infer a scope from,
+ * and rendering-triggered notifications are the client's responsibility
+ * once it calls `applyPropositions`.
+ */
+const createPersonalization = () => ({
+  lifecycle: {
+    /**
+     * @param {Object} params
+     * @param {any} params.event
+     * @param {string[]} [params.decisionScopes]
+     * @param {{ decisionScopes?: string[], surfaces?: string[] }} [params.personalization]
+     * @param {(callback: (arg: { response: any }) => Object) => void} params.onResponse
+     */
+    onBeforeEvent({
+      event,
+      decisionScopes = [],
+      personalization = {},
+      onResponse,
+    }) {
+      const scopes = dedupe([
+        ...decisionScopes,
+        ...(personalization.decisionScopes || []),
+      ]);
+      const surfaces = dedupe(personalization.surfaces || []);
+
+      if (scopes.length === 0 && surfaces.length === 0) {
+        return Promise.resolve();
+      }
+
+      event.mergeQuery({
+        personalization: { schemas: SCHEMAS, decisionScopes: scopes, surfaces },
+      });
+
+      onResponse(({ response }) => ({
+        propositions: response.getPayloadsByType(DECISIONS_HANDLE),
+      }));
+
+      return Promise.resolve();
+    },
+  },
+});
+
+createPersonalization.namespace = "Personalization";
+
+export default createPersonalization;

package/src/components/requiredComponentCreators.js

@@ -0,0 +1,17 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+// This file contains the components that are always active in a Node build,
+// regardless of what's passed to `components`. Mirrors the shape of
+// packages/browser/src/components/requiredComponentCreators.js.
+
+export { default as context } from "./context.js";

package/src/createNodeAlloy.js

@@ -0,0 +1,167 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/** @import { NetworkService, StorageService, CookieService, RuntimeService, LegacyService, GlobalsService } from "@adobe/alloy-core/services" */
+/** @import { Logger } from "@adobe/alloy-core/core/types.js" */
+
+import {
+  createCustomInstance as createCoreCustomInstance,
+  createCoreConfigs,
+} from "@adobe/alloy-core";
+import createNodePlatformServices from "./services/createNodePlatformServices.js";
+import * as allRequiredComponents from "./components/requiredComponentCreators.js";
+
+/** @import { NodeRequestLike } from "./services/createNodePlatformServices.js" */
+
+/**
+ * @typedef {Object} PlatformServiceOverrides
+ * @property {(logger: Logger) => NetworkService} [network]
+ * @property {StorageService} [storage]
+ * @property {CookieService} [cookie]
+ * @property {RuntimeService} [runtime]
+ * @property {LegacyService} [legacy]
+ * @property {GlobalsService} [globals]
+ */
+
+/**
+ * @typedef {(commandName: string, options?: Record<string, unknown>) => Promise<any>} ExecuteCommand
+ */
+
+// Everything but `configure`: available directly on a top-level instance and
+// on every bound handle returned by forRequest() (which is configured for
+// you). Kept in sync with core's required components (DataCollector,
+// Identity, LibraryInfo) — grows as Node picks up optional components.
+const COMMAND_NAMES = [
+  "setDebug",
+  "sendEvent",
+  "applyResponse",
+  "getIdentity",
+  "appendIdentityToUrl",
+  "getLibraryInfo",
+  "setConsent",
+];
+
+/**
+ * @param {ExecuteCommand} executeCommand
+ * @param {string[]} commandNames
+ * @returns {Record<string, (options?: Record<string, unknown>) => Promise<any>>}
+ */
+const bindCommandMethods = (executeCommand, commandNames) => {
+  /** @type {Record<string, (options?: Record<string, unknown>) => Promise<any>>} */
+  const methods = {};
+  commandNames.forEach((commandName) => {
+    methods[commandName] = (options) => executeCommand(commandName, options);
+  });
+  return methods;
+};
+
+/**
+ * Node entrypoint's method-based wrapper around core's string-command
+ * dispatcher. Unlike the browser bundle, there's no pre-load stub queue to
+ * keep call syntax uniform for, so real methods give better discoverability
+ * and typo-safety than `alloy("commandName", options)`.
+ *
+ * @param {Object} [params]
+ * @param {string} [params.name]
+ * @param {Array<Object>} [params.monitors]
+ * @param {Array<Function>} [params.components]
+ * @param {PlatformServiceOverrides} [params.platformServices]
+ */
+const createNodeAlloy = ({
+  name,
+  monitors,
+  components = [],
+  platformServices = {},
+} = {}) => {
+  // Mirrors packages/browser/src/index.js: components a consumer can't opt
+  // out of (currently just Context), prepended to whatever they passed in.
+  const allComponents = [
+    ...Object.values(allRequiredComponents),
+    ...components,
+  ];
+
+  const executeCommand = createCoreCustomInstance(
+    { name, monitors, components: allComponents },
+    () => createNodePlatformServices(platformServices),
+    createCoreConfigs(),
+  );
+
+  /** @type {Record<string, unknown> | undefined} */
+  let capturedConfig;
+
+  /**
+   * A handle scoped to a single request, backed by its own fresh instance
+   * reconfigured with this instance's config plus `requestOverrides`
+   * layered on top of its platformServices. Requires `configure()` to have
+   * already resolved on this instance.
+   *
+   * A fresh instance (not just a swapped `cookie`) is required because
+   * Identity caches its resolved ECID in a plain closure for the life of
+   * the instance — reusing one across requests would leak identity between
+   * visitors regardless of which cookie jar was passed in.
+   *
+   * For the same reason, `cookie`/`storage` never fall back to this
+   * instance's own platformServices; only the stateless
+   * `network`/`runtime`/`legacy`/`globals` slots do.
+   *
+   * `request` (any object with a `headers` property — a Node
+   * `IncomingMessage`, an Express `req`, a fetch `Request`, etc.) is the
+   * real incoming request this call is proxying, used to forward the
+   * visitor's real headers to Edge Network and populate
+   * `web.webPageDetails.URL` (see components/context.js).
+   *
+   * @param {PlatformServiceOverrides & { request?: NodeRequestLike }} [requestOverrides]
+   */
+  const forRequest = (requestOverrides = {}) => {
+    if (!capturedConfig) {
+      throw new Error(
+        "forRequest() can only be called after configure() has resolved.",
+      );
+    }
+    const { request, ...requestPlatformServices } = requestOverrides;
+    const { cookie, storage, ...sharedPlatformServices } = platformServices;
+    const requestExecuteCommand = createCoreCustomInstance(
+      { name, monitors, components: allComponents },
+      () =>
+        createNodePlatformServices({
+          ...sharedPlatformServices,
+          ...requestPlatformServices,
+          request,
+        }),
+      // Fresh validators per request: orgId/datastreamId are being
+      // reconfigured with the exact same values on purpose here, once per
+      // request, so they must not be checked for uniqueness against every
+      // other request this process has ever handled.
+      createCoreConfigs(),
+    );
+    requestExecuteCommand("configure", capturedConfig);
+    return bindCommandMethods(requestExecuteCommand, COMMAND_NAMES);
+  };
+
+  return {
+    ...bindCommandMethods(executeCommand, COMMAND_NAMES),
+    /** @param {Record<string, unknown>} options */
+    configure(options) {
+      // Only capture the config once configure() has actually succeeded —
+      // if it rejects (invalid config), capturedConfig must stay unset, so
+      // a subsequent forRequest() call still throws instead of silently
+      // reconfiguring every request with a config core already rejected.
+      return executeCommand("configure", options).then((result) => {
+        capturedConfig = options;
+        return result;
+      });
+    },
+    forRequest,
+  };
+};
+
+export default createNodeAlloy;

package/src/index.js

@@ -0,0 +1,63 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+import createNodeAlloy from "./createNodeAlloy.js";
+import * as allOptionalComponents from "./allOptionalComponents.js";
+
+/**
+ * @alpha
+ *
+ * Creates a custom Node instance, including only the given optional
+ * components (e.g. `personalization`). See `createInstance` to get every
+ * optional component by default.
+ *
+ * Returns an object with real methods (`configure`, `sendEvent`,
+ * `getIdentity`, ...) rather than the browser bundle's
+ * `alloy("commandName", options)` calling convention — there's no pre-load
+ * stub queue to keep call syntax uniform for in Node, so methods give
+ * better discoverability. This is an early skeleton: most optional
+ * components (Consent, Audiences, etc.) are not wired up yet.
+ *
+ * @param {Object} [options]
+ * @param {Array<Function>} [options.components]
+ * @param {Object} [options.platformServices] Overrides for one or more of
+ * the default Node platform services (network, storage, cookie, runtime,
+ * legacy, globals) — e.g. a `cookie` service backed by a real HTTP
+ * request/response so identity persists across requests instead of only
+ * within a single process. See `createNodePlatformServices` for the shape
+ * of each override.
+ */
+export const createCustomInstance = ({
+  platformServices = {},
+  components = [],
+  ...options
+} = {}) =>
+  createNodeAlloy({
+    ...options,
+    components,
+    platformServices,
+  });
+
+/**
+ * @alpha
+ *
+ * Creates a Node instance with every optional component included.
+ *
+ * @param {Object} [options]
+ * @param {Object} [options.platformServices]
+ */
+export const createInstance = (options = {}) =>
+  createCustomInstance({
+    ...options,
+    components: Object.values(allOptionalComponents),
+  });
+
+export { allOptionalComponents as components };

package/src/services/createNodeCookieService.js

@@ -0,0 +1,54 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/** @import { CookieService } from "@adobe/alloy-core/services" */
+
+/**
+ * In-memory only; there is no HTTP request/response to read or write real
+ * cookie headers against yet, so identity/consent state does not persist
+ * across process restarts or across requests in a server context.
+ *
+ * The `jar` and `converter` params are the recursion seam for `withConverter`,
+ * mirroring the browser cookie service built on js-cookie.
+ *
+ * @param {Map<string, string>} [jar]
+ * @param {{ read?: Function, write?: Function }} [converter]
+ * @returns {CookieService}
+ */
+const createNodeCookieService = (jar = new Map(), converter = {}) => ({
+  get: (name) => {
+    const value = jar.get(name);
+    if (value === undefined) {
+      return undefined;
+    }
+    return converter.read ? converter.read(value, name) : value;
+  },
+  getAll: () => {
+    /** @type {Record<string, string>} */
+    const result = {};
+    jar.forEach((value, name) => {
+      result[name] = converter.read ? converter.read(value, name) : value;
+    });
+    return result;
+  },
+  set: (name, value) => {
+    const finalValue = converter.write ? converter.write(value, name) : value;
+    jar.set(name, finalValue);
+    return finalValue;
+  },
+  remove: (name) => {
+    jar.delete(name);
+  },
+  withConverter: (newConverter) => createNodeCookieService(jar, newConverter),
+});
+
+export default createNodeCookieService;

package/src/services/createNodeGlobalsService.js

@@ -0,0 +1,43 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/** @import { GlobalsService } from "@adobe/alloy-core/services" */
+
+/**
+ * There is no page, DOM, or `<script>` queue in Node, so anything tied to
+ * those concepts falls back to an empty/static default.
+ *
+ * @returns {GlobalsService}
+ */
+const createNodeGlobalsService = () => ({
+  getInstanceNames: () => [],
+  getInstanceQueue: () => [],
+  getMonitors: () => [],
+  getLocationSearch: () => "",
+  getLocationHash: () => "",
+  getUserAgent: () => "",
+  getHostname: () => "",
+  getPageLocation: () => ({ host: "", pathname: "" }),
+  isPageSsl: () => true,
+  fireReferrerHideableImage: async () => {},
+  getWindowContext: () => ({
+    title: "",
+    url: "",
+    referrer: "",
+    height: 0,
+    width: 0,
+    scrollY: 0,
+    scrollX: 0,
+  }),
+});
+
+export default createNodeGlobalsService;

package/src/services/createNodeLegacyService.js

@@ -0,0 +1,26 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/** @import { LegacyService } from "@adobe/alloy-core/services" */
+
+/**
+ * Visitor.js and `adobe.optIn` are browser-only legacy libraries with no
+ * Node equivalent, so this service is a no-op.
+ *
+ * @returns {LegacyService}
+ */
+const createNodeLegacyService = () => ({
+  getEcidFromVisitor: async () => undefined,
+  awaitVisitorOptIn: async () => {},
+});
+
+export default createNodeLegacyService;

package/src/services/createNodeNetworkService.js

@@ -0,0 +1,55 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/** @import { NetworkService } from "@adobe/alloy-core/services" */
+
+/**
+ * Node has no `navigator.sendBeacon`, so there is no separate unload-safe
+ * transport — both network strategies use `fetch`.
+ *
+ * @param {Object} [options]
+ * @param {Record<string, string>} [options.headers] Extra headers merged
+ * into every outgoing request (e.g. from `pickForwardableHeaders`). Can't
+ * override `Content-Type`.
+ * @returns {NetworkService}
+ */
+const createNodeNetworkService = ({ headers: forwardedHeaders = {} } = {}) => {
+  /**
+   * @param {string} url
+   * @param {string} body
+   */
+  const sendFetchRequest = (url, body) =>
+    fetch(url, {
+      method: "POST",
+      headers: {
+        ...forwardedHeaders,
+        "Content-Type": "text/plain; charset=UTF-8",
+      },
+      body,
+    }).then((response) =>
+      response.text().then((responseBody) => ({
+        statusCode: response.status,
+        /** @param {string} name */
+        getHeader(name) {
+          return response.headers.get(name);
+        },
+        body: responseBody,
+      })),
+    );
+
+  return {
+    sendFetchRequest,
+    sendBeaconRequest: sendFetchRequest,
+  };
+};
+
+export default createNodeNetworkService;

package/src/services/createNodePlatformServices.js

@@ -0,0 +1,77 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/** @import { NetworkService, StorageService, CookieService, RuntimeService, LegacyService, GlobalsService, PlatformServices } from "@adobe/alloy-core/services" */
+/** @import { Logger } from "@adobe/alloy-core/core/types.js" */
+
+import createNodeNetworkService from "./createNodeNetworkService.js";
+import createNodeStorageService from "./createNodeStorageService.js";
+import createNodeCookieService from "./createNodeCookieService.js";
+import createNodeRuntimeService from "./createNodeRuntimeService.js";
+import createNodeLegacyService from "./createNodeLegacyService.js";
+import createNodeGlobalsService from "./createNodeGlobalsService.js";
+import pickForwardableHeaders from "./pickForwardableHeaders.js";
+
+/**
+ * @typedef {Record<string, string | string[] | undefined> | Headers} NodeRequestHeaders
+ * Either a plain headers object (Node's `IncomingMessage.headers`,
+ * Express's `req.headers`) or a WHATWG `Headers` instance (fetch-standard
+ * `Request.headers`). See `getHeader.js`.
+ */
+
+/**
+ * @typedef {Object} NodeRequestLike
+ * @property {NodeRequestHeaders} [headers]
+ */
+
+/**
+ * Each override replaces the corresponding default in-memory Node
+ * implementation wholesale — e.g. pass a `cookie` service backed by a real
+ * HTTP request/response or a database to persist identity across requests.
+ *
+ * @param {Object} [overrides]
+ * @param {(logger: Logger) => NetworkService} [overrides.network]
+ * @param {StorageService} [overrides.storage]
+ * @param {CookieService} [overrides.cookie]
+ * @param {RuntimeService} [overrides.runtime]
+ * @param {LegacyService} [overrides.legacy]
+ * @param {GlobalsService} [overrides.globals]
+ * @param {NodeRequestLike} [overrides.request] The real incoming request
+ * Node is proxying an event for, if any — forwarded to Edge Network via
+ * `pickForwardableHeaders` (unless `network` is overridden), and exposed
+ * as-is on the returned object for the Context component to read.
+ * @returns {PlatformServices & { request?: NodeRequestLike }}
+ */
+const createNodePlatformServices = ({
+  network,
+  storage,
+  cookie,
+  runtime,
+  legacy,
+  globals,
+  request,
+} = {}) => ({
+  createNetworkService: (logger) =>
+    network
+      ? network(logger)
+      : createNodeNetworkService({
+          headers: pickForwardableHeaders(request?.headers),
+        }),
+  storage: storage || createNodeStorageService(),
+  cookie: cookie || createNodeCookieService(),
+  runtime: runtime || createNodeRuntimeService(),
+  legacy: legacy || createNodeLegacyService(),
+  globals: globals || createNodeGlobalsService(),
+  request,
+});
+
+export default createNodePlatformServices;

package/src/services/createNodeRuntimeService.js

@@ -0,0 +1,26 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/** @import { RuntimeService } from "@adobe/alloy-core/services" */
+
+/** @returns {RuntimeService} */
+const createNodeRuntimeService = () => ({
+  setTimeout: globalThis.setTimeout.bind(globalThis),
+  clearTimeout: globalThis.clearTimeout.bind(globalThis),
+  atob: globalThis.atob.bind(globalThis),
+  btoa: globalThis.btoa.bind(globalThis),
+  TextEncoder: globalThis.TextEncoder,
+  TextDecoder: globalThis.TextDecoder,
+  now: () => Date.now(),
+});
+
+export default createNodeRuntimeService;

package/src/services/createNodeStorageService.js

@@ -0,0 +1,53 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/** @import { Storage, NamespacedStorage, StorageService } from "@adobe/alloy-core/services" */
+
+/**
+ * In-memory only; nothing persists across process restarts. A future
+ * revision can back this with a file, Redis, etc.
+ *
+ * @returns {Storage}
+ */
+const createMemoryStorage = () => {
+  const store = new Map();
+  return {
+    getItem(name) {
+      return Promise.resolve(store.has(name) ? store.get(name) : null);
+    },
+    setItem(name, value) {
+      store.set(name, value);
+      return Promise.resolve(true);
+    },
+    removeItem(name) {
+      store.delete(name);
+      return Promise.resolve(true);
+    },
+    clear() {
+      store.clear();
+      return Promise.resolve(true);
+    },
+  };
+};
+
+/** @returns {StorageService} */
+const createNodeStorageService = () => ({
+  createNamespacedStorage() {
+    /** @type {NamespacedStorage} */
+    return {
+      session: createMemoryStorage(),
+      persistent: createMemoryStorage(),
+    };
+  },
+});
+
+export default createNodeStorageService;

package/src/services/getHeader.js

@@ -0,0 +1,35 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/** @import { NodeRequestHeaders } from "./createNodePlatformServices.js" */
+
+/**
+ * Reads a single header from either shape `request.headers` can be — a
+ * plain object, or a WHATWG `Headers` instance (e.g. fetch-standard
+ * `Request`s, as used by Next.js Route Handlers, Hono, etc.), which only
+ * exposes values through `.get()`.
+ *
+ * @param {NodeRequestHeaders | undefined} headers
+ * @param {string} name Lowercase header name.
+ * @returns {string | string[] | undefined}
+ */
+const getHeader = (headers, name) => {
+  if (!headers) {
+    return undefined;
+  }
+  if (headers instanceof Headers) {
+    return headers.get(name) ?? undefined;
+  }
+  return headers[name];
+};
+
+export default getHeader;

package/src/services/index.js

@@ -0,0 +1,19 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+export { default as createNodeNetworkService } from "./createNodeNetworkService.js";
+export { default as createNodeStorageService } from "./createNodeStorageService.js";
+export { default as createNodeCookieService } from "./createNodeCookieService.js";
+export { default as createNodeRuntimeService } from "./createNodeRuntimeService.js";
+export { default as createNodeLegacyService } from "./createNodeLegacyService.js";
+export { default as createNodeGlobalsService } from "./createNodeGlobalsService.js";
+export { default as createNodePlatformServices } from "./createNodePlatformServices.js";

package/src/services/pickForwardableHeaders.js

@@ -0,0 +1,55 @@
+/*
+Copyright 2026 Adobe. All rights reserved.
+This file is licensed to you under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License. You may obtain a copy
+of the License at http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software distributed under
+the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+OF ANY KIND, either express or implied. See the License for the specific language
+governing permissions and limitations under the License.
+*/
+
+/** @import { NodeRequestHeaders } from "./createNodePlatformServices.js" */
+
+import getHeader from "./getHeader.js";
+
+// Forwarded so Edge Network's own device/locale/geo parsing sees the real
+// visitor instead of this Node process.
+const FORWARDABLE_HEADER_NAMES = [
+  "user-agent",
+  "accept-language",
+  // User-Agent Client Hints
+  "sec-ch-ua",
+  "sec-ch-ua-mobile",
+  "sec-ch-ua-platform",
+  "sec-ch-ua-platform-version",
+  "sec-ch-ua-arch",
+  "sec-ch-ua-bitness",
+  "sec-ch-ua-full-version-list",
+  "sec-ch-ua-model",
+  "sec-ch-ua-wow64",
+  // Client IP, as set by a proxy/load balancer in front of this server —
+  // otherwise Edge Network attributes every request to this server's IP.
+  "x-forwarded-for",
+  "forwarded",
+  "x-real-ip",
+];
+
+/**
+ * @param {NodeRequestHeaders} [headers]
+ * @returns {Record<string, string>}
+ */
+const pickForwardableHeaders = (headers) => {
+  /** @type {Record<string, string>} */
+  const picked = {};
+  FORWARDABLE_HEADER_NAMES.forEach((name) => {
+    const value = getHeader(headers, name);
+    if (typeof value === "string" && value) {
+      picked[name] = value;
+    }
+  });
+  return picked;
+};
+
+export default pickForwardableHeaders;