@godaddy/gd-commerce-server 0.1.1 → 0.2.0

package/README.md

@@ -57,3 +57,24 @@ 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.
+
+### Connection state
+
+Hosts can implement the optional synchronous `CommerceConfiguration.readConnectionState()`
+method. Its return type is exported as `CommerceConnectionState` (`unbound | connecting | ready`).
+Returning `undefined` keeps the existing behavior. Throw when the state is unknown or cannot be
+read. The default environment configuration does not implement this method, so missing
+credentials never count as `unbound`.
+
+`GET /config` returns `{ state: 'unbound' }` or `{ state: 'connecting' }` without reading store
+credentials. `ready` includes the usual opaque `cartScope` and `currencyCode` after `read()`
+succeeds. Without this method, the successful response shape is unchanged. All responses are
+uncached; a malformed state or unavailable configuration returns 503. Data and checkout routes,
+and the in-process checkout and order helpers, reject any state other than `ready` before
+upstream calls.
+
+The host owns the connection lifecycle. Report `ready` only after the store connection is
+complete. Lost configuration is an error, never evidence of `unbound`. After a store connects,
+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.

package/dist/index.d.ts

@@ -39,7 +39,10 @@ interface CommerceConfig {
   /** Optional host-owned attribution shared by draft orders and checkout. */
   owner?: string;
 }
+type CommerceConnectionState = 'unbound' | 'connecting' | 'ready';
 interface CommerceConfiguration {
+  /** Authoritative host state. Missing support preserves legacy live/error behavior. */
+  readConnectionState?(): CommerceConnectionState | undefined;
   read(): CommerceConfig;
   readCheckout(): CommerceCheckoutConfiguration;
 }
@@ -143,4 +146,4 @@ declare function createCommerceRouter(options?: CreateCommerceRouterOptions): Ro
 declare function createCommerceCatalogRouter(configuration?: CommerceConfiguration): Router;
 declare function createGoDaddyPaymentsRouter(configuration?: CommerceConfiguration, checkoutReturnUrls?: CheckoutReturnUrls): Router;
 //#endregion
-export { type CheckoutReturnUrls, type CheckoutSession, type CommerceCheckoutConfiguration, type CommerceCheckoutShippingConfiguration, type CommerceConfig, type CommerceConfiguration, 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, type CommerceOrderStatus, type CommerceRouterFeatures, type CreateCheckoutSessionParams, type CreateCommerceRouterOptions, type RuntimeCommerceConfigurationOptions, createCheckoutSession, createCommerceCatalogRouter, createCommerceRouter, createGoDaddyPaymentsRouter, createRuntimeCommerceConfiguration, getOrderStatus, parseCommerceCheckoutConfiguration, readCommerceConfig };

package/dist/index.js

@@ -79,7 +79,14 @@ function commerceConfigurationForResponse(res) {
 	return createRuntimeCommerceConfiguration();
 }
 function readCommerceConfigForResponse(res) {
-	return commerceConfigurationForResponse(res).read();
+	const configuration = commerceConfigurationForResponse(res);
+	assertCommerceConnectionReady(configuration);
+	return configuration.read();
+}
+/** Nonready and invalid connection states must never use leftover credentials. */
+function assertCommerceConnectionReady(configuration) {
+	const state = configuration.readConnectionState?.();
+	if (state !== void 0 && state !== "ready") throw new Error("Commerce store connection is not ready. Complete the store connection before continuing.");
 }
 
 //#endregion
@@ -330,6 +337,7 @@ async function createCheckoutSession(params, configuration = createRuntimeCommer
 		skuId,
 		lineItemData
 	].filter(Boolean).length !== 1) throw new Error("createCheckoutSession: exactly one of draftOrderId, skuId, or lineItemData is required");
+	assertCommerceConnectionReady(configuration);
 	const { storeId, channelId, clientId, clientSecret, apiBaseUrl, sourceApp, owner, currencyCode: configCurrencyCode } = configuration.read();
 	const checkoutConfiguration = configuration.readCheckout();
 	const enablePromotionCodes = promotionCodesEnabled(checkoutConfiguration);
@@ -420,6 +428,7 @@ async function createCheckoutSession(params, configuration = createRuntimeCommer
 //#region src/lib/commerce/get-order-status.ts
 async function getOrderStatus(orderId, configuration = createRuntimeCommerceConfiguration()) {
 	if (typeof orderId !== "string" || !orderId.trim() || orderId === "." || orderId === "..") throw new Error("getOrderStatus: a valid orderId is required");
+	assertCommerceConnectionReady(configuration);
 	const { storeId, channelId, clientId, clientSecret, apiBaseUrl, currencyCode } = configuration.read();
 	const token = await getOAuthAccessToken({
 		clientId,
@@ -1065,6 +1074,7 @@ async function handler$6(req, res) {
 			return;
 		}
 		if (req.headers?.["x-commerce-scope"] !== void 0) {
+			assertCommerceConnectionReady(configuration);
 			if (!validateCommerceCartScope(req, res, configuration.read())) return;
 		}
 		const validateReturnUrls = res.locals.commerceCheckoutReturnUrlValidator;
@@ -1097,8 +1107,16 @@ async function handler$6(req, res) {
 async function handler$7(_req, res) {
 	res.setHeader("Cache-Control", "no-store");
 	try {
-		const config = commerceConfigurationForResponse(res).read();
+		const configuration = commerceConfigurationForResponse(res);
+		const state = configuration.readConnectionState?.();
+		if (state === "unbound" || state === "connecting") {
+			res.json({ state });
+			return;
+		}
+		if (state !== void 0 && state !== "ready") throw new Error("Invalid Commerce connection state.");
+		const config = configuration.read();
 		res.json({
+			...state === "ready" ? { state } : {},
 			cartScope: getCommerceCartScope(config),
 			currencyCode: config.currencyCode
 		});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@godaddy/gd-commerce-server",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Opinionated Express server integration for GoDaddy Commerce",
   "type": "module",
   "license": "MIT",