@godaddy/gd-commerce-server 0.2.0 → 0.3.0

package/README.md

@@ -56,7 +56,7 @@ Configure `checkoutReturnUrls` on the router using trusted deployment settings.
 
 Without this policy, HTTP checkout returns 503 before creating a session. Invalid request destinations return 400. This applies to both router presets that expose checkout. Trusted in-process callers of `createCheckoutSession()` own their return URLs and must construct or validate them server-side.
 
-A return from hosted checkout is not proof of payment. The order-status route uses the authorized Orders REST API, which supports completed orders, and returns its payment status (for example `PAID` or `PENDING`; `unknown` if absent). The server OAuth client must be granted `commerce.order:read`. The helper verifies the returned order ID, store, and channel and returns a limited summary without customer contact data. Hosts must authenticate callers and authorize access to each requested order before exposing this route.
+A return from hosted checkout is not proof of payment. The order-status route uses the authorized Orders REST API, which supports completed orders, and returns its payment status (for example `PAID` or `PENDING`; the exported `ORDER_STATUS_UNKNOWN`, `'unknown'`, if absent). Show it only as display enrichment and never present an unconfirmed payment as paid. The server OAuth client must be granted `commerce.order:read`. The helper verifies the returned order ID, store, and channel and returns a limited summary without customer contact data. The route returns 400 for a missing, blank, padded, `.`, or `..` order ID (padded IDs are rejected, not trimmed) or one the Orders API rejects as malformed (422 `VALIDATION_FAILED`), and 404 when the Orders API reports the order missing (404 `NOT_FOUND`) or the order belongs to another store or channel. A 404 without that code, such as from a misconfigured API base URL, is an upstream failure. Token and other Commerce failures, including a response for a different order ID, return 502 and unreadable configuration returns 503 (see [Errors](#errors)). Hosts must authenticate callers and authorize access to each requested order before exposing this route.
 
 ### Connection state
 
@@ -78,3 +78,30 @@ complete. Lost configuration is an error, never evidence of `unbound`. After a s
 report `unbound` again only after it is deliberately disconnected. The storefront package owns
 the generic sample products and local sample cart; this server never creates sample Commerce
 records or simulates checkout.
+
+## Errors
+
+Every route reports failures the same way. The body is `{ "error": "<customer-facing message>", "code": "<code>", "requestId": "<id>" }` (order-status also includes `success: false`). The same id is passed to the logger. Bodies never contain upstream messages, configuration details, or credentials.
+
+| Status | `code` | Meaning |
+| --- | --- | --- |
+| 400 | `invalid_request` | Missing or invalid input. |
+| 404 | `not_found` | Missing order or product, or a write to an existing cart (`/cart/:id/...`) that is missing, expired, or completed. Cart reads keep returning `200 { "cart": null }`. Checkout with a stale or completed `draftOrderId` is not yet distinguished and returns 502. |
+| 409 | `scope_mismatch` | `X-Commerce-Scope` no longer matches the configured store binding. |
+| 502 | `upstream_unauthorized` | Commerce rejected this server's OAuth client or requested scope (HTTP 401/403, or an OAuth 400 with `invalid_client`, `invalid_grant`, `unauthorized_client`, or `invalid_scope`). It concerns server credentials, not the caller, so it is never reported as 401/403. |
+| 502 | `upstream_error` | Commerce failed, returned an unexpected response, or could not be reached. |
+| 503 | `not_configured` | Configuration is missing or unreadable, the host reports a connection state other than `ready`, or checkout return URLs are not configured. |
+| 500 | `internal_error` | An unexpected error in this package. |
+
+Upstream errors without a specific mapping stay 502; business errors such as invalid discount codes are not yet distinguished. 5xx detail, including upstream status and GraphQL error codes, goes to the logger:
+
+```ts
+createCommerceRouter({
+  configuration,
+  logger: { error: (message, context) => log.error(context, message) },
+  // Use the host's request id when its edge sets one; unsafe or missing ids fall back to a UUID.
+  getRequestId: (req) => req.get('x-request-id'),
+});
+```
+
+`createCommerceCatalogRouter` and `createGoDaddyPaymentsRouter` accept the same `{ logger, getRequestId }` as their last argument. The logger defaults to `console.error`. In-process helpers throw the exported `CommerceError` subclasses (`InvalidRequestError`, `NotFoundError`, `CommerceNotConfiguredError`, `UpstreamError`), including when a host configuration throws while being read. Check `error.code` (for example `'not_found'`) rather than `instanceof`, which fails when a host has more than one copy of this package.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Router } from "express";
+import { Request, Router } from "express";
 
 //#region src/lib/commerce/checkout-config.d.ts
 /** Shipping options accepted by the hosted checkout API. Omit to use the store's configuration. */
@@ -21,6 +21,86 @@ interface CheckoutReturnUrls {
   successUrls: readonly string[];
 }
 //#endregion
+//#region src/lib/commerce/errors.d.ts
+/**
+ * Typed failures for the Commerce routes and helpers.
+ *
+ * Domain code throws these; `commerceRoute` is the only place that turns them into HTTP
+ * responses. `message` is internal and only logged. `publicMessage` is safe to show a shopper;
+ * when it is absent the route's failure label is used instead.
+ */
+type CommerceErrorCode = 'invalid_request' | 'scope_mismatch' | 'not_found' | 'not_configured' | 'upstream_unauthorized' | 'upstream_error' | 'internal_error';
+interface CommerceErrorOptions {
+  cause?: unknown;
+  publicMessage?: string;
+  /** Internal diagnostics for the server log. Never sent to the browser. */
+  details?: Record<string, unknown>;
+}
+declare class CommerceError extends Error {
+  readonly httpStatus: number;
+  readonly code: CommerceErrorCode;
+  readonly publicMessage?: string;
+  readonly details?: Record<string, unknown>;
+  constructor(httpStatus: number, code: CommerceErrorCode, message: string, options?: CommerceErrorOptions);
+}
+interface ClientErrorOptions extends Omit<CommerceErrorOptions, 'publicMessage'> {
+  /** Internal message for in-process callers; defaults to the public message. */
+  message?: string;
+}
+declare class InvalidRequestError extends CommerceError {
+  constructor(publicMessage: string, {
+    message,
+    ...options
+  }?: ClientErrorOptions);
+}
+declare class ScopeMismatchError extends CommerceError {
+  constructor();
+}
+declare class NotFoundError extends CommerceError {
+  constructor(publicMessage: string, {
+    message,
+    ...options
+  }?: ClientErrorOptions);
+}
+declare class CommerceNotConfiguredError extends CommerceError {
+  constructor(message: string, {
+    publicMessage,
+    ...options
+  }?: CommerceErrorOptions);
+}
+interface UpstreamErrorOptions extends Omit<CommerceErrorOptions, 'publicMessage'> {
+  /** The upstream rejected this server's own credentials (OAuth client or scope). */
+  unauthorized?: boolean;
+}
+/**
+ * Commerce returned a failure, an unexpected response, or could not be reached. Always 502:
+ * even an upstream 401/403 concerns this server's client credentials, not the caller, and
+ * answering 401 would collide with the host's own authentication handling.
+ */
+declare class UpstreamError extends CommerceError {
+  constructor(message: string, {
+    unauthorized,
+    ...options
+  }?: UpstreamErrorOptions);
+}
+//#endregion
+//#region src/lib/commerce/commerce-route.d.ts
+interface CommerceErrorLogContext {
+  requestId: string;
+  method: string;
+  path: string;
+  httpStatus: number;
+  code: CommerceErrorCode;
+  details?: Record<string, unknown>;
+  error: unknown;
+}
+/** Receives server-side failure detail that is never sent to the browser. */
+interface CommerceLogger {
+  error(message: string, context: CommerceErrorLogContext): void;
+}
+/** Returns the host's id for this request (for example one set by its load balancer), if any. */
+type CommerceRequestIdResolver = (req: Request) => string | undefined;
+//#endregion
 //#region src/lib/commerce/config.d.ts
 interface CommerceConfig {
   /** Public OAuth client id. */
@@ -59,7 +139,6 @@ declare function readCommerceConfig(options?: RuntimeCommerceConfigurationOption
 declare function createRuntimeCommerceConfiguration(options?: RuntimeCommerceConfigurationOptions): CommerceConfiguration;
 //#endregion
 //#region src/lib/commerce/checkout-subgraph.d.ts
-
 interface CheckoutSessionLineItemPriceDataInput {
   /** Price per unit in the currency's smallest unit (e.g. cents for USD). */
   unitAmount: number;
@@ -113,10 +192,12 @@ interface CheckoutSession {
 declare function createCheckoutSession(params: CreateCheckoutSessionParams, configuration?: CommerceConfiguration): Promise<CheckoutSession>;
 //#endregion
 //#region src/lib/commerce/get-order-status.d.ts
+/** `CommerceOrderStatus.status` when the Orders API reports no payment status. */
+declare const ORDER_STATUS_UNKNOWN = "unknown";
 interface CommerceOrderStatus {
   /** GoDaddy order id. */
   id: string;
-  /** Payment status reported by Commerce, or 'unknown' when it is unavailable. */
+  /** Payment status reported by Commerce (e.g. `PAID`, `PENDING`), or `ORDER_STATUS_UNKNOWN`. */
   status: string;
   /** Total amount in the currency's smallest unit (cents for USD). */
   amount: number;
@@ -129,6 +210,12 @@ interface CommerceOrderStatus {
   /** Line item summaries, excluding private order metadata. */
   lineItems?: unknown[];
 }
+declare class InvalidOrderIdError extends InvalidRequestError {
+  constructor();
+}
+declare class OrderNotFoundError extends NotFoundError {
+  constructor();
+}
 declare function getOrderStatus(orderId: string, configuration?: CommerceConfiguration): Promise<CommerceOrderStatus>;
 //#endregion
 //#region src/router.d.ts
@@ -136,14 +223,24 @@ interface CommerceRouterFeatures {
   catalog?: boolean;
   payments?: boolean;
 }
-interface CreateCommerceRouterOptions {
+/** Where failure detail is logged and how each request's id is chosen. */
+interface CommerceRouterObservabilityOptions {
+  /** Receives 5xx failure detail. Defaults to `console.error`. */
+  logger?: CommerceLogger;
+  /**
+   * Returns the host's id for the request, for example `(req) => req.get('x-request-id')` when
+   * the host's edge sets that header. Invalid or missing ids fall back to a random UUID.
+   */
+  getRequestId?: CommerceRequestIdResolver;
+}
+interface CreateCommerceRouterOptions extends CommerceRouterObservabilityOptions {
   configuration?: CommerceConfiguration;
   features?: CommerceRouterFeatures;
   /** Required to enable browser checkout; never derived from request headers. */
   checkoutReturnUrls?: CheckoutReturnUrls;
 }
 declare function createCommerceRouter(options?: CreateCommerceRouterOptions): Router;
-declare function createCommerceCatalogRouter(configuration?: CommerceConfiguration): Router;
-declare function createGoDaddyPaymentsRouter(configuration?: CommerceConfiguration, checkoutReturnUrls?: CheckoutReturnUrls): Router;
+declare function createCommerceCatalogRouter(configuration?: CommerceConfiguration, observability?: CommerceRouterObservabilityOptions): Router;
+declare function createGoDaddyPaymentsRouter(configuration?: CommerceConfiguration, checkoutReturnUrls?: CheckoutReturnUrls, observability?: CommerceRouterObservabilityOptions): Router;
 //#endregion
-export { type CheckoutReturnUrls, type CheckoutSession, type CommerceCheckoutConfiguration, type CommerceCheckoutShippingConfiguration, type CommerceConfig, type CommerceConfiguration, type CommerceConnectionState, type CommerceOrderStatus, type CommerceRouterFeatures, type CreateCheckoutSessionParams, type CreateCommerceRouterOptions, type RuntimeCommerceConfigurationOptions, createCheckoutSession, createCommerceCatalogRouter, createCommerceRouter, createGoDaddyPaymentsRouter, createRuntimeCommerceConfiguration, getOrderStatus, parseCommerceCheckoutConfiguration, readCommerceConfig };
+export { type CheckoutReturnUrls, type CheckoutSession, type CommerceCheckoutConfiguration, type CommerceCheckoutShippingConfiguration, type CommerceConfig, type CommerceConfiguration, type CommerceConnectionState, CommerceError, type CommerceErrorCode, type CommerceErrorLogContext, type CommerceLogger, CommerceNotConfiguredError, type CommerceOrderStatus, type CommerceRequestIdResolver, type CommerceRouterFeatures, type CommerceRouterObservabilityOptions, type CreateCheckoutSessionParams, type CreateCommerceRouterOptions, InvalidOrderIdError, InvalidRequestError, NotFoundError, ORDER_STATUS_UNKNOWN, OrderNotFoundError, type RuntimeCommerceConfigurationOptions, ScopeMismatchError, UpstreamError, createCheckoutSession, createCommerceCatalogRouter, createCommerceRouter, createGoDaddyPaymentsRouter, createRuntimeCommerceConfiguration, getOrderStatus, parseCommerceCheckoutConfiguration, readCommerceConfig };