Support commerce storefront components before a store is connected

[sbolinger-godaddy]

Summary

These changes let the commerce storefront components run on a site that is not connected to Commerce yet. The goal is to show a catalog list and a cart in something like an Airo App Builder (AAB) template before the merchant connects a store. When a store connects, the same components switch to real catalog and cart data. No source changes or page reload are needed.

@godaddy/gd-commerce-server

• CommerceConfiguration has a new optional readConnectionState() method. It returns unbound, connecting, or ready. A new CommerceConnectionState type is exported.
• GET /config returns { state: 'unbound' } or { state: 'connecting' } without reading store credentials. A ready response keeps the usual cartScope and currencyCode. A host that does not implement the method gets the same response shape as before.
• Product, cart, and checkout routes, and the in-process checkout and order-status helpers, reject requests unless the state is ready. This happens before any upstream call.

@godaddy/gd-commerce-storefront

• Catalog has a new sampleProducts prop. Six generic products (Product 1–6, $10–$60 USD) appear only while the server reports unbound. When a store is connected, the prop has no effect, and real empty, loading, and error states are never replaced by samples.
• The cart button and drawer use a sample cart that is kept in memory only. You can add items, change quantities, and remove items. Sample mode makes no product, cart, or checkout requests, does not use live cart storage, and has no checkout.
• The provider exposes the unbound and connecting states. While it is not ready, it re-reads configuration every 5 seconds when the page is visible, so connecting a store activates the live catalog automatically. A failed refresh immediately shows an error and never falls back to samples.
• Rendered sample surfaces carry data-commerce-source="sample".

Compatibility: older clients treat the new unbound response as an error, not as permission to show samples. Hosts that don't report connection state keep their current behavior. The library has no host-specific code; AAB is one host that will implement readConnectionState().

Changeset

• Changeset added (docs): .changeset/sample-products-before-connection.md, minor for both packages.

Test Plan

Tested locally in AAB a simulated template scenario. Empty components were added to a real AAB app, then the agent was asked to connect real products and checkout. Everything worked fine. Need to publish for a full test.

• pnpm --filter @godaddy/gd-commerce-server test: 176 passed. Covers the config states, rejection of non-ready states on data and checkout routes, and legacy response compatibility.
• pnpm --filter @godaddy/gd-commerce-storefront test: 41 passed. Covers:
  • sample catalog and cart behavior, with no requests beyond the config read;
  • catalog opt-in and inert product details while unbound;
  • suspending samples on the first failed config refresh;
  • automatic activation by polling;
  • ignoring a stale unbound response after a ready one;
  • existing live cart behavior.
• Typecheck passes for both packages. biome check passes for the storefront package.
• Not yet verified against a real AAB template and a real store connection. That integration happens in AAB after this package is released.

[changeset-bot]

🦋 Changeset detected

Latest commit: 6674271

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@godaddy/gd-commerce-storefront	Minor
@godaddy/gd-commerce-server	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR