@adobe/alloy-node 0.1.0 → 0.2.0

package/README.md

@@ -100,6 +100,19 @@ separate wiring needed. If you build a custom instance with
 `setConsent` will still exist as a method but will reject when called, the
 same as calling an unregistered command in the browser bundle.
 
+> [!WARNING]
+> `defaultConsent: "pending"` is rejected by `configure()` — not supported
+> in Node. A pending `sendEvent()`/`getIdentity()` on one `forRequest()`
+> call can only ever be released by a `setConsent()` on that *exact same*
+> call, never by a later request for the same visitor (each `forRequest()`
+> is a fresh instance with its own private pending queue) — unlike a
+> browser page, Node has no equivalent long-lived session to hold that
+> state across separate HTTP requests. Use `"in"` or `"out"`, and gate
+> calling `sendEvent()`/`setConsent()` on your own persisted consent
+> decision instead. If you need the multi-request pending flow to work,
+> let us know — we haven't built it because we don't yet have signal that
+> anyone needs it, not because it's impossible.
+
 ## Context
 
 A minimal, always-on Context component attaches `implementationDetails` to
@@ -124,6 +137,95 @@ 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.
 
+## Authenticated requests (Edge Network Server API, v2)
+
+Because Node runs in a trusted, client-controlled environment (unlike a
+browser), it authenticates its own requests instead of sending them
+unauthenticated — `configure()` **requires** OAuth Server-to-Server
+credentials from the [Adobe Developer Console](https://developer.adobe.com/console):
+
+```js
+await alloy.configure({
+  orgId: "...",
+  datastreamId: "...",
+  edgeCredentials: {
+    clientId: "...",
+    clientSecret: "...",
+    scopes: ["openid", "AdobeID", ...], // whatever your project grants
+  },
+});
+```
+
+`configure()` rejects if `edgeCredentials` is missing — unlike the browser
+bundle, where the same config field is optional (and generally shouldn't be
+used at all: shipping a client secret to a browser defeats the point of it
+being a secret). `sendEvent()` then goes to the authenticated Edge Network
+Server API (`server.adobedc.net`, `v2`) instead of the standard one, with a
+real IMS access token attached.
+
+The IMS token is fetched once and cached (~24h) for the life of the
+process, not once per request — it's server-credential state, not visitor
+state, shared automatically across every `forRequest()` call the same way
+`network`/`runtime` already are.
+
+### Running the real-network integration suite
+
+`packages/node/test/integration/nodeConsumer.spec.js` makes requests to
+authentication-required APIs, so it needs a real credential — it reads
+`CLIENT_ID`/`CLIENT_SECRET`/`SCOPES`/`IMS_ORG_ID`/`DATASTREAM_ID` from
+`process.env` and skips itself (doesn't fail) whenever any of them are
+unset. `DATASTREAM_ID` must be a real datastream under that same
+`IMS_ORG_ID`.
+
+Because it needs credentials, this suite does not run with the basic
+`pnpm run test`/`test:coverage` testing commands (which exclude it via
+`--project=!node-integration`) into its own command:
+
+```sh
+# Locally, from a .env file at the repo root (gitignored):
+node --env-file=.env ./node_modules/.bin/vitest run --project node-integration
+# or, equivalently:
+node --env-file=.env ./node_modules/.bin/pnpm run test:node-integration
+```
+
+In CI (`.github/workflows/quality-checks.yml`'s `tests` job), `pnpm run
+test:node-integration` is its own step, with those same env vars populated
+from repo secrets — `ALLOY_NODE_INTEGRATION_CLIENT_ID`, `_CLIENT_SECRET`,
+`_SCOPES`, `_IMS_ORG_ID`, `_DATASTREAM_ID` — configured under this repo's
+**Settings → Secrets and variables → Actions**. Until those secrets exist,
+the suite just keeps skipping in CI, same as it does locally without a
+`.env`. GitHub doesn't expose secrets to a fork's `pull_request` run either
+way, so it'll always skip there regardless.
+
+Verified against a real, credentialed project — two things worth knowing,
+neither of which needs any code changes on your part, but do affect what
+you pass to `sendEvent()`:
+
+- **Only `sendEvent` uses v2.** `setConsent` and `getIdentity` still go
+  through the standard v1 endpoint even when `edgeCredentials` is
+  configured — the authenticated Server API returns a flat 404 for
+  `privacy/set-consent` and `identity/acquire`. This is handled
+  automatically; you don't need to do anything differently for those
+  calls.
+- **You must supply a primary identity.** Since there's no browser cookie
+  jar for Edge Network to resolve identity from on a pure server-to-server
+  call, an authenticated `sendEvent()` needs an explicit identity in the
+  event itself, or it's rejected:
+
+  ```js
+  await request.sendEvent({
+    xdm: {
+      eventType: "...",
+      identityMap: {
+        Email: [{ id: "visitor@example.com", primary: true }],
+      },
+    },
+  });
+  ```
+
+  (The `events` → `event` payload reshaping v2 requires under the hood is
+  handled internally — nothing to do there either.)
+
 ## Platform services
 
 Both `createInstance(options)` and `forRequest(overrides)` accept a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/alloy-node",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Adobe Experience Platform Web SDK - Node.js entrypoint",
   "type": "module",
   "repository": {
@@ -24,7 +24,7 @@
     }
   },
   "dependencies": {
-    "@adobe/alloy-core": "^1.2.3"
+    "@adobe/alloy-core": "^1.3.0"
   },
   "scripts": {
     "typecheck": "tsc -p jsconfig.json"

package/src/alloy-core.d.ts

@@ -4,9 +4,19 @@ declare module "@adobe/alloy-core" {
     options: Record<string, unknown>,
     createPlatformServices?: () => unknown,
     coreConfigValidators?: unknown,
+    getImsAccessToken?: { getAccessToken: () => Promise<string> },
   ): (commandName: string, options?: Record<string, unknown>) => Promise<any>;
 
   export function createCoreConfigs(): unknown;
 
+  export function createGetImsAccessToken(options: {
+    edgeCredentials: {
+      clientId: string;
+      clientSecret: string;
+      scopes: string[];
+      imsHost: string;
+    };
+  }): { getAccessToken: () => Promise<string> };
+
   export function consent(options: Record<string, unknown>): unknown;
 }

package/src/components/context.js

@@ -15,7 +15,7 @@ governing permissions and limitations under the License.
 import packageJson from "../../package.json" with { type: "json" };
 import getHeader from "../services/getHeader.js";
 
-const LIBRARY_NAME = "https://ns.adobe.com/experience/alloy";
+const LIBRARY_NAME = "https://ns.adobe.com/experience/alloy-node";
 const { version: LIBRARY_VERSION } = packageJson;
 
 /**

package/src/createNodeAlloy.js

@@ -16,7 +16,9 @@ governing permissions and limitations under the License.
 import {
   createCustomInstance as createCoreCustomInstance,
   createCoreConfigs,
+  createGetImsAccessToken,
 } from "@adobe/alloy-core";
+import { DEFAULT_IMS_HOST } from "@adobe/alloy-core/constants/domain.js";
 import createNodePlatformServices from "./services/createNodePlatformServices.js";
 import * as allRequiredComponents from "./components/requiredComponentCreators.js";
 
@@ -97,6 +99,10 @@ const createNodeAlloy = ({
 
   /** @type {Record<string, unknown> | undefined} */
   let capturedConfig;
+  // Built once, after configure() resolves, and shared across every
+  // forRequest() call — see createGetImsAccessToken's docs for why.
+  /** @type {ReturnType<typeof createGetImsAccessToken> | undefined} */
+  let sharedGetImsAccessToken;
 
   /**
    * A handle scoped to a single request, backed by its own fresh instance
@@ -142,6 +148,7 @@ const createNodeAlloy = ({
       // request, so they must not be checked for uniqueness against every
       // other request this process has ever handled.
       createCoreConfigs(),
+      sharedGetImsAccessToken,
     );
     requestExecuteCommand("configure", capturedConfig);
     return bindCommandMethods(requestExecuteCommand, COMMAND_NAMES);
@@ -151,12 +158,48 @@ const createNodeAlloy = ({
     ...bindCommandMethods(executeCommand, COMMAND_NAMES),
     /** @param {Record<string, unknown>} options */
     configure(options) {
+      if (options.defaultConsent === "pending") {
+        return Promise.reject(
+          new Error(
+            '@adobe/alloy-node does not support defaultConsent: "pending" — ' +
+              "Node has no cross-request session to hold a pending decision " +
+              'in (unlike a long-lived browser page). Use "in" or "out", and ' +
+              "gate calling sendEvent()/setConsent() on your own persisted " +
+              "consent decision instead.",
+          ),
+        );
+      }
+
+      // Node runs in a trusted, client-controlled environment, so
+      // authenticating is required here, unlike the browser bundle's
+      // optional opt-in.
+      if (!options.edgeCredentials) {
+        return Promise.reject(
+          new Error(
+            "@adobe/alloy-node requires edgeCredentials. See the README for " +
+              "how to obtain OAuth Server-to-Server credentials from the " +
+              "Adobe Developer Console.",
+          ),
+        );
+      }
+
       // 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;
+        // core's config validation applies this same default, but only to
+        // its own internal copy — this instance's token accessor is built
+        // from the raw options, so an omitted imsHost would otherwise
+        // become the literal string "undefined" in the token URL.
+        const edgeCredentials = /** @type {any} */ (options).edgeCredentials;
+        sharedGetImsAccessToken = createGetImsAccessToken({
+          edgeCredentials: {
+            ...edgeCredentials,
+            imsHost: edgeCredentials.imsHost || DEFAULT_IMS_HOST,
+          },
+        });
         return result;
       });
     },

package/src/services/createNodeNetworkService.js

@@ -26,12 +26,15 @@ const createNodeNetworkService = ({ headers: forwardedHeaders = {} } = {}) => {
   /**
    * @param {string} url
    * @param {string} body
+   * @param {Record<string, string>} [perCallHeaders] e.g. IMS auth headers
+   * for an authenticated Server API request. Can't override `Content-Type`.
    */
-  const sendFetchRequest = (url, body) =>
+  const sendFetchRequest = (url, body, perCallHeaders) =>
     fetch(url, {
       method: "POST",
       headers: {
         ...forwardedHeaders,
+        ...perCallHeaders,
         "Content-Type": "text/plain; charset=UTF-8",
       },
       body,

package/src/services/createNodePlatformServices.js

@@ -13,6 +13,7 @@ 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 packageJson from "../../package.json" with { type: "json" };
 import createNodeNetworkService from "./createNodeNetworkService.js";
 import createNodeStorageService from "./createNodeStorageService.js";
 import createNodeCookieService from "./createNodeCookieService.js";
@@ -49,7 +50,7 @@ import pickForwardableHeaders from "./pickForwardableHeaders.js";
  * 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 }}
+ * @returns {PlatformServices & { request?: NodeRequestLike, libraryVersionOverride: string }}
  */
 const createNodePlatformServices = ({
   network,
@@ -72,6 +73,9 @@ const createNodePlatformServices = ({
   legacy: legacy || createNodeLegacyService(),
   globals: globals || createNodeGlobalsService(),
   request,
+  // Node ships unbundled source, so the build-time __VERSION__ placeholder
+  // never gets replaced — report the real package.json version instead.
+  libraryVersionOverride: packageJson.version,
 });
 
 export default createNodePlatformServices;