@reactionary/ucp 0.0.1

package/lib/reactionary-ucp-server.js

@@ -0,0 +1,102 @@
+import {
+  createInitialRequestContext,
+  MemoryCache
+} from "@reactionary/core";
+import {
+} from "./reactionary-ucp-common.js";
+import { getOrCreateSessionId, jsonResponse, sendWebResponse, toWebRequest, UCP_SESSION_ID_HEADER } from "./reactionary-ucp-http.js";
+import { createUCPProfile, getRequestRoute } from "./reactionary-ucp-profile.js";
+import { handleRestRequest, UCPHttpError } from "./reactionary-ucp-rest.js";
+import { ReactionaryUCPSessionStore } from "./reactionary-ucp-session-store.js";
+class ReactionaryUCPServer {
+  constructor(clientFactory, options = {}) {
+    this.clientFactory = clientFactory;
+    this.options = options;
+    this.sessionStore = new ReactionaryUCPSessionStore(
+      this.options.sessionCache ?? new MemoryCache(),
+      this.options.sessionTtlSeconds ?? 60 * 60 * 24
+    );
+  }
+  clientFactory;
+  options;
+  sessionStore;
+  async fetch(request) {
+    const sessionId = getOrCreateSessionId(request);
+    const requestContext = await this.createRequestContext(sessionId);
+    const client = this.clientFactory(requestContext);
+    const response = await this.handleRequest(request, client, sessionId);
+    await this.sessionStore.put(sessionId, requestContext.session);
+    response.headers.set(UCP_SESSION_ID_HEADER, sessionId);
+    const requestId = request.headers.get("Request-Id");
+    if (requestId) {
+      response.headers.set("Request-Id", requestId);
+    }
+    return response;
+  }
+  getHandler() {
+    return {
+      fetch: (request) => this.fetch(request),
+      close: () => this.close()
+    };
+  }
+  toNodeHandler() {
+    return async (request, response) => {
+      const webResponse = await this.fetch(await toWebRequest(request));
+      await sendWebResponse(response, webResponse);
+    };
+  }
+  close() {
+    return Promise.resolve();
+  }
+  async createRequestContext(sessionId) {
+    const restoredSession = await this.sessionStore.get(sessionId);
+    const requestContext = createInitialRequestContext();
+    if (restoredSession) {
+      requestContext.session = restoredSession;
+    }
+    return requestContext;
+  }
+  async handleRequest(request, client, sessionId) {
+    const route = getRequestRoute(request, this.options.profile);
+    if (request.method === "OPTIONS") {
+      return new Response(null, {
+        status: 204,
+        headers: {
+          allow: "GET, HEAD, OPTIONS, POST, PUT"
+        }
+      });
+    }
+    if (route.path === "/.well-known/ucp" && request.method === "GET") {
+      return jsonResponse(createUCPProfile(client, this.options.profile));
+    }
+    try {
+      const restResponse = await handleRestRequest(
+        request,
+        client,
+        route.path,
+        sessionId,
+        this.sessionStore
+      );
+      if (restResponse) {
+        return restResponse;
+      }
+    } catch (error) {
+      if (error instanceof UCPHttpError) {
+        return jsonResponse(error.body, { status: error.status });
+      }
+      throw error;
+    }
+    return jsonResponse({
+      error: {
+        code: "NOT_FOUND",
+        message: `No UCP route matched ${request.method} ${route.path}.`
+      }
+    }, {
+      status: 404,
+      omitBody: request.method === "HEAD"
+    });
+  }
+}
+export {
+  ReactionaryUCPServer
+};

package/lib/reactionary-ucp-session-store.js

@@ -0,0 +1,63 @@
+import { SessionSchema } from "@reactionary/core";
+import * as z from "zod";
+const SESSION_CACHE_KEY_PREFIX = "reactionary:ucp:session";
+const IDEMPOTENCY_CACHE_KEY_PREFIX = "reactionary:ucp:idempotency";
+const UCPActionResponseSchema = z.looseObject({});
+const UCPIdempotencyRecordSchema = z.looseObject({
+  action: z.string(),
+  fingerprint: z.string().optional(),
+  status: z.number().optional(),
+  response: UCPActionResponseSchema
+});
+class ReactionaryUCPSessionStore {
+  constructor(cache, ttlSeconds) {
+    this.cache = cache;
+    this.ttlSeconds = ttlSeconds;
+  }
+  cache;
+  ttlSeconds;
+  async get(sessionId) {
+    return await this.cache.get(
+      this.getCacheKey(sessionId),
+      SessionSchema
+    ) ?? void 0;
+  }
+  async put(sessionId, session) {
+    await this.cache.invalidate([this.getDependencyId(sessionId)]);
+    await this.cache.put(this.getCacheKey(sessionId), session, {
+      ttlSeconds: this.ttlSeconds,
+      dependencyIds: [this.getDependencyId(sessionId)]
+    });
+  }
+  async getIdempotencyRecord(sessionId, idempotencyKey) {
+    return await this.cache.get(
+      this.getIdempotencyCacheKey(sessionId, idempotencyKey),
+      UCPIdempotencyRecordSchema
+    ) ?? void 0;
+  }
+  async putIdempotencyRecord(sessionId, idempotencyKey, record) {
+    await this.cache.put(
+      this.getIdempotencyCacheKey(sessionId, idempotencyKey),
+      record,
+      {
+        ttlSeconds: this.ttlSeconds,
+        dependencyIds: [this.getIdempotencyDependencyId(sessionId)]
+      }
+    );
+  }
+  getCacheKey(sessionId) {
+    return `${SESSION_CACHE_KEY_PREFIX}:${sessionId}`;
+  }
+  getDependencyId(sessionId) {
+    return `${SESSION_CACHE_KEY_PREFIX}:${sessionId}`;
+  }
+  getIdempotencyCacheKey(sessionId, idempotencyKey) {
+    return `${IDEMPOTENCY_CACHE_KEY_PREFIX}:${sessionId}:${encodeURIComponent(idempotencyKey)}`;
+  }
+  getIdempotencyDependencyId(sessionId) {
+    return `${IDEMPOTENCY_CACHE_KEY_PREFIX}:${sessionId}`;
+  }
+}
+export {
+  ReactionaryUCPSessionStore
+};

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@reactionary/ucp",
+  "version": "0.0.1",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./src/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Solteq/reactionary.git"
+  },
+  "dependencies": {
+    "@reactionary/core": "0.0.1",
+    "zod": "4.1.9"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.9"
+  },
+  "sideEffects": false
+}

package/src/index.d.ts

@@ -0,0 +1 @@
+export * from './lib/reactionary-ucp-server.js';

package/src/lib/reactionary-ucp-capabilities.d.ts

@@ -0,0 +1,4 @@
+import { BaseCapability } from '@reactionary/core';
+import type { ReactionaryUCPClient } from './reactionary-ucp-common.js';
+export declare function hasCapability(client: ReactionaryUCPClient, name: string): boolean;
+export declare function getCapability(client: ReactionaryUCPClient, name: string): BaseCapability | undefined;

package/src/lib/reactionary-ucp-common.d.ts

@@ -0,0 +1,71 @@
+import type { Cache, Cart, Checkout, Client, FacetValueIdentifier, Order, Product, ProductSearchResult, RequestContext, Result } from '@reactionary/core';
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { components } from './ucp-shopping.openapi.js';
+type UCPService = components['schemas']['base'];
+type UCPCapability = components['schemas']['$defs-base'];
+type UCPPaymentHandler = components['schemas']['payment_handler_$defs-base'];
+export interface ReactionaryUCPProfile {
+    ucp: {
+        version: string;
+        services: Record<string, UCPService[]>;
+        capabilities: Record<string, UCPCapability[]>;
+        payment_handlers?: Record<string, UCPPaymentHandler[]>;
+    };
+    keys: Array<Record<string, unknown>>;
+    merchant: {
+        name: string;
+        url: string;
+        contact: {
+            email: string;
+            phone_number?: string;
+        };
+    };
+}
+type UCPMethod<TMethod extends (payload: never) => Promise<unknown>, TValue> = (payload: Parameters<TMethod>[0]) => Promise<Result<TValue, unknown>>;
+export type ReactionaryUCPClient = object & {
+    productSearch?: {
+        createCategoryNavigationFilter?: UCPMethod<Client['productSearch']['createCategoryNavigationFilter'], FacetValueIdentifier>;
+        queryByTerm: UCPMethod<Client['productSearch']['queryByTerm'], ProductSearchResult>;
+    };
+    product?: {
+        getById: UCPMethod<Client['product']['getById'], Product>;
+        getBySKU: UCPMethod<Client['product']['getBySKU'], Product>;
+    };
+    cart?: {
+        add: UCPMethod<Client['cart']['add'], Cart>;
+        changeQuantity: UCPMethod<Client['cart']['changeQuantity'], Cart>;
+        createCart: UCPMethod<Client['cart']['createCart'], Cart>;
+        deleteCart: UCPMethod<Client['cart']['deleteCart'], void>;
+        getById: UCPMethod<Client['cart']['getById'], Cart>;
+        remove: UCPMethod<Client['cart']['remove'], Cart>;
+    };
+    checkout?: {
+        addPaymentInstruction: UCPMethod<Client['checkout']['addPaymentInstruction'], Checkout>;
+        finalizeCheckout: UCPMethod<Client['checkout']['finalizeCheckout'], Checkout>;
+        getById: UCPMethod<Client['checkout']['getById'], Checkout>;
+        initiateCheckoutForCart: UCPMethod<Client['checkout']['initiateCheckoutForCart'], Checkout>;
+    };
+    order?: {
+        getById: UCPMethod<Client['order']['getById'], Order>;
+    };
+};
+export type ReactionaryUCPClientFactory<TClient extends ReactionaryUCPClient = ReactionaryUCPClient> = (requestContext: RequestContext) => TClient;
+export interface ReactionaryUCPServerOptions {
+    sessionCache?: Cache;
+    sessionTtlSeconds?: number;
+    profile?: ReactionaryUCPProfileOptions;
+}
+export interface ReactionaryUCPProfileOptions {
+    endpoint: string;
+    merchant: ReactionaryUCPProfile['merchant'];
+    keys: ReactionaryUCPProfile['keys'];
+    services?: ReactionaryUCPProfile['ucp']['services'];
+    capabilities?: ReactionaryUCPProfile['ucp']['capabilities'];
+    paymentHandlers?: ReactionaryUCPProfile['ucp']['payment_handlers'];
+}
+export interface ReactionaryUCPHttpHandler {
+    fetch(request: Request): Promise<Response>;
+    close(): Promise<void>;
+}
+export type ReactionaryUCPNodeRequestHandler = (request: IncomingMessage, response: ServerResponse) => Promise<void>;
+export {};

package/src/lib/reactionary-ucp-http.d.ts

@@ -0,0 +1,12 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export declare const UCP_SESSION_ID_HEADER = "ucp-session-id";
+type ProtocolHeaders = Headers | Record<string, string>;
+export declare function getOrCreateSessionId(request: Request): string;
+export declare function jsonResponse(body: unknown, options?: {
+    status?: number;
+    headers?: ProtocolHeaders;
+    omitBody?: boolean;
+}): Response;
+export declare function toWebRequest(request: IncomingMessage): Promise<Request>;
+export declare function sendWebResponse(response: ServerResponse, webResponse: Response): Promise<void>;
+export {};

package/src/lib/reactionary-ucp-profile.d.ts

@@ -0,0 +1,5 @@
+import type { ReactionaryUCPClient, ReactionaryUCPProfile, ReactionaryUCPProfileOptions } from './reactionary-ucp-common.js';
+export declare function getRequestRoute(request: Request, profile: ReactionaryUCPProfileOptions | undefined): {
+    path: string;
+};
+export declare function createUCPProfile(client: ReactionaryUCPClient, profile: ReactionaryUCPProfileOptions | undefined): ReactionaryUCPProfile;

package/src/lib/reactionary-ucp-rest.d.ts

@@ -0,0 +1,8 @@
+import type { ReactionaryUCPClient } from './reactionary-ucp-common.js';
+import type { ReactionaryUCPSessionStore } from './reactionary-ucp-session-store.js';
+export declare function handleRestRequest(request: Request, client: ReactionaryUCPClient, path: string, sessionId: string, sessionStore: ReactionaryUCPSessionStore): Promise<Response | undefined>;
+export declare class UCPHttpError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, body: unknown);
+}

package/src/lib/reactionary-ucp-server.d.ts

@@ -0,0 +1,14 @@
+import { type ReactionaryUCPClient, type ReactionaryUCPClientFactory, type ReactionaryUCPHttpHandler, type ReactionaryUCPNodeRequestHandler, type ReactionaryUCPProfile, type ReactionaryUCPProfileOptions, type ReactionaryUCPServerOptions } from './reactionary-ucp-common.js';
+export type { ReactionaryUCPClient, ReactionaryUCPClientFactory, ReactionaryUCPHttpHandler, ReactionaryUCPNodeRequestHandler, ReactionaryUCPProfile, ReactionaryUCPProfileOptions, ReactionaryUCPServerOptions, };
+export declare class ReactionaryUCPServer<TClient extends ReactionaryUCPClient = ReactionaryUCPClient> {
+    private readonly clientFactory;
+    private readonly options;
+    private readonly sessionStore;
+    constructor(clientFactory: ReactionaryUCPClientFactory<TClient>, options?: ReactionaryUCPServerOptions);
+    fetch(request: Request): Promise<Response>;
+    getHandler(): ReactionaryUCPHttpHandler;
+    toNodeHandler(): ReactionaryUCPNodeRequestHandler;
+    close(): Promise<void>;
+    private createRequestContext;
+    private handleRequest;
+}

package/src/lib/reactionary-ucp-session-store.d.ts

@@ -0,0 +1,23 @@
+import { type Cache, type Session } from '@reactionary/core';
+import * as z from 'zod';
+declare const UCPIdempotencyRecordSchema: z.ZodObject<{
+    action: z.ZodString;
+    fingerprint: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodNumber>;
+    response: z.ZodObject<{}, z.core.$loose>;
+}, z.core.$loose>;
+export type UCPIdempotencyRecord = z.infer<typeof UCPIdempotencyRecordSchema>;
+export declare class ReactionaryUCPSessionStore {
+    private readonly cache;
+    private readonly ttlSeconds;
+    constructor(cache: Cache, ttlSeconds: number);
+    get(sessionId: string): Promise<Session | undefined>;
+    put(sessionId: string, session: Session): Promise<void>;
+    getIdempotencyRecord(sessionId: string, idempotencyKey: string): Promise<UCPIdempotencyRecord | undefined>;
+    putIdempotencyRecord(sessionId: string, idempotencyKey: string, record: UCPIdempotencyRecord): Promise<void>;
+    private getCacheKey;
+    private getDependencyId;
+    private getIdempotencyCacheKey;
+    private getIdempotencyDependencyId;
+}
+export {};