@godaddy/gd-commerce-server 0.1.0

package/LICENSE.md

@@ -0,0 +1,3 @@
+Copyright 2026 GoDaddy.com Operating Company, LLC
+
+Licensed under the MIT License.

package/README.md

@@ -0,0 +1,59 @@
+# @godaddy/gd-commerce-server
+
+An opinionated Express router for GoDaddy Commerce catalog, cart, and hosted checkout APIs.
+
+```ts
+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](docs/checkout-configuration.md) 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.
+
+```ts
+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.
+
+## 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`; `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.

package/dist/index.d.ts

@@ -0,0 +1,146 @@
+import { 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. */
+interface CommerceCheckoutShippingConfiguration {
+  readonly originAddress?: Readonly<Record<string, unknown>>;
+  readonly fulfillmentLocationId?: string;
+}
+interface CommerceCheckoutConfiguration {
+  readonly enablePromotionCodes: boolean;
+  readonly enableTaxCollection: boolean;
+  readonly enableShipping: boolean;
+  readonly shipping?: CommerceCheckoutShippingConfiguration;
+}
+declare function parseCommerceCheckoutConfiguration(raw: string | undefined): CommerceCheckoutConfiguration;
+//#endregion
+//#region src/lib/commerce/checkout-return-urls.d.ts
+/** Exact host-owned checkout destinations. Only success URLs may add an orderId query parameter. */
+interface CheckoutReturnUrls {
+  returnUrls: readonly string[];
+  successUrls: readonly string[];
+}
+//#endregion
+//#region src/lib/commerce/config.d.ts
+interface CommerceConfig {
+  /** Public OAuth client id. */
+  clientId: string;
+  /** Server-only OAuth client secret. Never expose to the browser. */
+  clientSecret: string;
+  storeId: string;
+  /** Sales channel used for orders and checkout. */
+  channelId: string;
+  /** HTTPS API origin. The default configuration uses https://api.godaddy.com. */
+  apiBaseUrl: string;
+  /** ISO 4217 currency code used when seeding empty cart totals. */
+  currencyCode: string;
+  /** Optional host-owned checkout attribution. Never read from request bodies. */
+  sourceApp?: string;
+  /** Optional host-owned attribution shared by draft orders and checkout. */
+  owner?: string;
+}
+interface CommerceConfiguration {
+  read(): CommerceConfig;
+  readCheckout(): CommerceCheckoutConfiguration;
+}
+interface RuntimeCommerceConfigurationOptions {
+  /** Server environment containing credentials, store/channel IDs, currency, and checkout flags. */
+  environment?: NodeJS.ProcessEnv;
+  /** Explicit server-controlled API origin override. Defaults to production. */
+  apiBaseUrl?: string;
+  sourceApp?: string;
+  owner?: string;
+}
+/** Read server environment values on each call. Loading files or secret stores belongs to the host. */
+declare function readCommerceConfig(options?: RuntimeCommerceConfigurationOptions): CommerceConfig;
+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;
+  /** ISO 4217 currency code. If omitted, the server injects it from GODADDY_CURRENCY_CODE. */
+  currencyCode?: string;
+}
+interface CheckoutSessionLineItemDataInput {
+  name: string;
+  priceData: CheckoutSessionLineItemPriceDataInput;
+}
+//#endregion
+//#region src/lib/commerce/create-checkout-session.d.ts
+interface CreateCheckoutSessionParams {
+  /** Where the hosted checkout sends the shopper on cancel/back. */
+  returnUrl: string;
+  /** Where the hosted checkout sends the shopper after payment. */
+  successUrl: string;
+  /** Existing cart/draft order to convert to a checkout session. */
+  draftOrderId?: string;
+  /** Buy-Now path; checkout is built from a single SKU line item. */
+  skuId?: string;
+  /** Quantity for Buy-Now / non-catalog paths. Defaults to 1. */
+  quantity?: number;
+  /**
+   * Non-catalog path; price the customer pays directly without a SKU or
+   * catalog product. Mutually exclusive with `skuId` and `draftOrderId`.
+   */
+  lineItemData?: CheckoutSessionLineItemDataInput;
+}
+interface CheckoutSession {
+  /** Hosted checkout URL to redirect the shopper to. */
+  url: string;
+  /** Checkout session id (not the order id). */
+  id: string;
+  /**
+   * Draft order id when the API created one (cart + Buy-Now flows). `null` for
+   * non-catalog sessions, which have no draft order.
+   */
+  draftOrderId: string | null;
+  /** Store id returned by checkout-api after it accepts the session. */
+  storeId: string;
+  /** Sales channel id returned by checkout-api after it accepts the session. */
+  channelId: string;
+  /** Commerce business that owns the selected store. */
+  businessId: string | null;
+  /** Store display name returned by checkout-api. */
+  storeName: string | null;
+  /** Server-owned source identifier used for transaction attribution. */
+  sourceApp: string | null;
+}
+declare function createCheckoutSession(params: CreateCheckoutSessionParams, configuration?: CommerceConfiguration): Promise<CheckoutSession>;
+//#endregion
+//#region src/lib/commerce/get-order-status.d.ts
+interface CommerceOrderStatus {
+  /** GoDaddy order id. */
+  id: string;
+  /** Payment status reported by Commerce, or 'unknown' when it is unavailable. */
+  status: string;
+  /** Total amount in the currency's smallest unit (cents for USD). */
+  amount: number;
+  /** ISO 4217 currency code (e.g. "USD"). */
+  currency: string;
+  /** ISO 8601 creation timestamp. */
+  createdAt?: string;
+  /** ISO 8601 last-updated timestamp. */
+  updatedAt?: string;
+  /** Line item summaries, excluding private order metadata. */
+  lineItems?: unknown[];
+}
+declare function getOrderStatus(orderId: string, configuration?: CommerceConfiguration): Promise<CommerceOrderStatus>;
+//#endregion
+//#region src/router.d.ts
+interface CommerceRouterFeatures {
+  catalog?: boolean;
+  payments?: boolean;
+}
+interface CreateCommerceRouterOptions {
+  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;
+//#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 };