npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@godaddy/gd-commerce-server

v0.4.1

Published

Opinionated Express server integration for GoDaddy Commerce

Readme

@godaddy/gd-commerce-server

An opinionated Express router for GoDaddy Commerce catalog, cart, and hosted checkout APIs.

import express from 'express';
import { createCommerceRouter, createRuntimeCommerceConfiguration } from '@godaddy/gd-commerce-server';

const app = express();
app.use(express.json());
app.use('/api/commerce', createCommerceRouter({
  configuration: createRuntimeCommerceConfiguration(),
  checkoutReturnUrls: {
    returnUrls: ['https://shop.example.com/shop'],
    successUrls: ['https://shop.example.com/checkout/success'],
  },
}));

The default configuration reads these server-only environment variables on each request:

  • GODADDY_OAUTH_CLIENT_ID and GODADDY_OAUTH_CLIENT_SECRET
  • GODADDY_STORE_ID and GODADDY_CHANNEL_ID
  • GODADDY_CURRENCY_CODE
  • Optional GODADDY_CHECKOUT_CONFIGURATION: JSON with boolean enablePromotionCodes, enableTaxCollection, and enableShipping fields. All three default to false when this variable is absent or malformed so configuration discovery cannot prevent checkout creation. Optional shipping accepts the checkout API's originAddress or fulfillmentLocationId; omit it to use store configuration.

See Checkout configuration for the temporary build-time synchronization flow and its eventual-consistency limitation.

The API origin defaults to https://api.godaddy.com. The package does not load files, provision merchants, or assign application attribution. Hosts own these concerns and any readiness checks or retries before invoking Commerce.

Host configuration

For an alternate API origin, pass an explicit server-controlled option. It must be an HTTPS origin without credentials, a path, query, or fragment. The host is responsible for trusting the destination, which receives OAuth credentials. Request bodies never select the API origin or attribution.

const configuration = createRuntimeCommerceConfiguration({
  apiBaseUrl: process.env.COMMERCE_API_ORIGIN, // undefined uses production
  sourceApp: process.env.COMMERCE_SOURCE_APP,
  owner: process.env.COMMERCE_ORDER_OWNER,
});

apiBaseUrl controls catalog, order, and OAuth requests; checkout uses the corresponding checkout.commerce. subdomain. There is no built-in list of alternate environments. sourceApp and owner are optional host-owned attribution values: checkout uses both, while draft orders use owner. Supply values required by your Commerce integration; the package omits them by default.

Hosts with their own configuration service can implement CommerceConfiguration directly. read() returns clientId, clientSecret, storeId, channelId, currencyCode, apiBaseUrl, and optional attribution. readCheckout() returns the checkout flags and optional shipping settings. Return validated, ready-to-use settings from one consistent binding. Both functions run on the server; credentials must never reach browser code.

Routers and helpers

createCommerceCatalogRouter(configuration) installs catalog, public configuration, and cart routes. createGoDaddyPaymentsRouter(configuration, checkoutReturnUrls) installs checkout and read-only order-status routes without requiring catalog UI. createCommerceRouter({ configuration }) installs both by default or accepts explicit feature flags.

The HTTP checkout route accepts an existing draftOrderId or a direct skuId; Commerce resolves catalog prices. It rejects lineItemData. For non-catalog charges such as fixed-price deposits, calculate the amount on the server and call createCheckoutSession(params, configuration) directly. Never forward browser-supplied prices to this trusted helper. Server callers can also use getOrderStatus(orderId, configuration) without an HTTP loopback.

Product channel visibility

GET /products and GET /products/:id use the channel from the server configuration and request only ACTIVE products. Search, category filters, and explicit product IDs retain that channel filter. Product-detail requests for products unavailable on that channel return 404. Browser query parameters cannot select a different channel. Products configured for all channels remain available when the configured channel is active and registered to the store.

If a configured GODADDY_CHANNEL_ID is inactive or is not registered to the configured store, the Catalog API returns an empty product list and product-detail requests return 404. These are successful empty results from the Catalog API, not configuration errors. When an expected catalog is empty, verify that the channel is active and registered to GODADDY_STORE_ID, then check product status and channel assignments. A missing GODADDY_CHANNEL_ID is different: the default configuration reader rejects it with 503 not_configured.

The Catalog API resolves active store channels through the paginated /v1/commerce/channels endpoint when evaluating a channel filter. Those lookups are not currently cached by the Catalog API, so channel-filtered catalog requests can add upstream calls and latency.

These checks control product browsing. GET /skus/:id, cart creation (POST /cart), and item addition (POST /cart/:id/items) forward SKU IDs without this package checking whether their products are available on the configured channel. A 404 from product details does not establish that a SKU lookup or cart write will be rejected. Hosts that require channel-based restrictions on these operations must enforce them before forwarding the SKU IDs; browsing filters are not an authorization boundary.

Checkout return destinations

Configure checkoutReturnUrls on the router using trusted deployment settings. Both lists contain complete absolute HTTPS URLs; scheme, origin, port, path, and configured query parameters must match. Success URLs may add a single orderId query parameter. Additional query parameters, fragments, credentials, relative URLs, and unlisted destinations are rejected. Configure separate cancel and success destinations as shown above; do not derive the allowlist from request headers or request bodies.

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; 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). 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.

A site before its store connects

A template that shows the storefront's sample products before a store connects needs the catalog routes and an explicit connection state. Here COMMERCE_CONNECTION_STATE is a host-owned setting, set to unbound when the site is created and to ready by the host's connection flow. Read it from whatever records the connection; never derive it from missing GODADDY_* variables.

import express from 'express';
import { createCommerceCatalogRouter, createRuntimeCommerceConfiguration } from '@godaddy/gd-commerce-server';

const runtime = createRuntimeCommerceConfiguration();
const configuration = {
  ...runtime,
  readConnectionState() {
    const state = process.env.COMMERCE_CONNECTION_STATE;
    if (state === 'unbound' || state === 'connecting' || state === 'ready') return state;
    throw new Error('COMMERCE_CONNECTION_STATE must be unbound, connecting, or ready.');
  },
};

const app = express();
app.use(express.json());
// Before static files and any single-page app or SSR fallback, which would answer /api/commerce with HTML.
app.use('/api/commerce', createCommerceCatalogRouter(configuration));
app.use(express.static('dist'));

createCommerceCatalogRouter exposes no checkout routes, so a site without checkout needs no checkoutReturnUrls. GET /api/commerce/config should return {"state":"unbound"} as JSON. If it returns the app's HTML page, the router is not mounted, or a fallback route runs before it.

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:

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.