@01.software/sdk 0.32.0 → 0.33.0

package/README.md

@@ -168,8 +168,9 @@ const preview = await server.preview.detail(
 ```
 
 For product pages, `server.commerce.product.previewDetail({ id }, {
-previewToken })` returns the same shaped product detail as `detail()`, but allows
-the saved draft/unpublished record addressed by the preview token.
+previewToken })` returns the raw product detail payload for the saved
+draft/unpublished record addressed by the preview token. `detail()` wraps the
+published storefront payload in a `{ found, product | reason }` result.
 
 ## Getting product detail
 
@@ -179,19 +180,33 @@ The recommended way to fetch a single product is the shaped helper:
 import { createClient } from '@01.software/sdk'
 
 const client = createClient({
-  publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY!,
+  publishableKey: '<publishable-key>',
 })
 
-const product = await client.commerce.product.detail({
+const result = await client.commerce.product.detail({
   slug: 'every-peach-tee',
 })
-if (!product) {
-  return notFound() // returned null — product missing, unpublished, or not in this tenant
+if (!result.found) {
+  return notFound()
 }
+
+const { product } = result
 // product: { product, variants, options, brand, categories, tags, images, videos, listing }
 ```
 
-`detail()` returns `ProductDetail | null`. A `null` result covers every "no result" reason: `not_found`, `not_published`, `feature_disabled`. Render the same "not available" UI for all three. To recover the exact reason for triage, `404` maps to `null` rather than a thrown error — inspect `client.lastRequestId` and match against backend logs.
+`detail()` returns `ProductDetailResult`, a discriminated union:
+`{ found: true, product: ProductDetail } | { found: false, reason }`. The
+`reason` value is one of `not_found`, `not_published`, or
+`feature_disabled`, so storefronts can choose between a standard 404, preview
+CTA, or feature gating UI. Permission/auth errors, including 403 tenant
+mismatches, still throw
+typed `SDKError` subclasses and preserve request IDs through the existing
+`lastRequestId` / `onRequestId` path.
+
+The successful product payload exposes inventory rollups without sentinel
+values: `product.totalInventory` is the tracked stock sum across non-unlimited
+variants, `null` when no variants are tracked, and
+`product.hasUnlimitedVariant` signals whether any variant is unlimited.
 
 ### Product selection helpers
 
@@ -291,12 +306,12 @@ coexist without being interpreted as selection state.
 inspect grouped variant fields without a follow-up fetch. The by-ids response
 also returns `missing: string[]` for requested product IDs that were not found,
 not published, or not accessible; `docs` preserve the input `productIds` order
-for returned products. The card carries product-level hero media
-(`product.thumbnail` -> first `product.images` -> `null`), an aggregated
-price range across all option-value groups, and a `swatches[]` array
-derived from groups when there is more than one. Single-group products
-emit `swatches: []`; storefronts that disagree can read `item.groups`
-directly.
+for returned products. The helper populates optional `representativeVariant`, a
+PDP-seeded `href`, representative media (`product.thumbnail` -> first
+`product.images` -> representative variant media -> `null`), an aggregated price
+range across all option-value groups, and a `swatches[]` array derived from
+groups when there is more than one. Single-group products emit `swatches: []`;
+storefronts that disagree can read `item.groups` directly.
 
 ```ts
 import {
@@ -309,9 +324,10 @@ const cards: ProductListingCard[] = response.docs.map((item) =>
 )
 ```
 
-Each swatch carries a hint-only option-value href
-(`?opt.<optionId>=<valueId>`); the detail page resolves it through
-`resolveProductSelection(detail, { search })`.
+The card href seeds the same representative variant that the PDP resolves by
+default through `resolveProductSelection(detail)`. Each swatch carries a
+hint-only option-value href (`?opt.<optionId>=<valueId>`); the detail page
+resolves it through `resolveProductSelection(detail, { search })`.
 
 ## Advanced: direct Payload queries (escape hatch)
 
@@ -401,10 +417,11 @@ export const revalidate = 60 // ISR — adjust per page freshness need
 
 export default async function ProductPage({ params }) {
   const client = createClient({
-    publishableKey: process.env.NEXT_PUBLIC_SOFTWARE_PUBLISHABLE_KEY!,
+    publishableKey: '<publishable-key>',
   })
-  const product = await client.commerce.product.detail({ slug: params.slug })
-  if (!product) return notFound()
+  const result = await client.commerce.product.detail({ slug: params.slug })
+  if (!result.found) return notFound()
+  const { product } = result
   // ...
 }
 ```
@@ -739,7 +756,13 @@ await server.commerce.orders.updateTransaction({ pgPaymentId, status, paymentMet
 // Returns
 await server.commerce.orders.createReturn({ orderNumber, returnItems, refundAmount, reason? })
 await server.commerce.orders.updateReturn({ returnId, status })
-await server.commerce.orders.returnWithRefund({ orderNumber, returnItems, refundAmount, pgPaymentId })
+await server.commerce.orders.returnWithRefund({
+  orderNumber,
+  returnItems: [{ orderItem, quantity, restockingFee? }],
+  refundAmount,
+  returnShippingFee?,
+  pgPaymentId,
+})
 ```
 
 ### Commerce Discounts / Shipping

package/dist/client.cjs

@@ -1375,6 +1375,30 @@ var CartApi = class {
   }
 };
 
+// src/core/api/product-api.ts
+var PRODUCT_DETAIL_UNAVAILABLE_REASONS = /* @__PURE__ */ new Set([
+  "not_found",
+  "not_published",
+  "feature_disabled"
+]);
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function readProductDetailUnavailableReason(value) {
+  if (!isRecord(value)) return void 0;
+  const directReason = value.reason ?? value.code;
+  if (typeof directReason === "string" && PRODUCT_DETAIL_UNAVAILABLE_REASONS.has(directReason)) {
+    return directReason;
+  }
+  return readProductDetailUnavailableReason(value.body);
+}
+function productDetailResultFromError(error) {
+  if (!(error instanceof SDKError) || error.status !== 404) return void 0;
+  const reason = readProductDetailUnavailableReason(error.details);
+  if (!reason) return void 0;
+  return { found: false, reason };
+}
+
 // src/core/commerce/commerce-client.ts
 var CommerceClient = class {
   constructor(options) {
@@ -1409,9 +1433,14 @@ var CommerceClient = class {
       listingGroups: (params) => execute("/api/products/listing-groups", params),
       detail: async (params) => {
         try {
-          return await execute("/api/products/detail", params);
+          const product = await execute(
+            "/api/products/detail",
+            params
+          );
+          return { found: true, product };
         } catch (err) {
-          if (err instanceof NotFoundError) return null;
+          const notFoundResult = productDetailResultFromError(err);
+          if (notFoundResult) return notFoundResult;
           throw err;
         }
       }