@cimplify/sdk 0.49.1 → 0.49.2

package/dist/server.d.mts

@@ -84,21 +84,63 @@ declare const tags: {
     readonly order: (id: string) => string;
 };
 
-/** Next 16 `revalidateTag` profile arg — built-in name (`'max'`/`'hours'`/…) or `{expire: secs}`. */
-type RevalidateProfile$1 = string | {
-    expire: number;
-};
 /**
- * Invalidate every cache entry tagged with the products list. Call after a
- * Server Action that creates / deletes / reorders products. The optional
- * `profile` is the Next 16 cacheLife profile (defaults to `'max'` SWR).
+ * Cimplify's opinionated cacheLife profiles for storefront server caches.
+ *
+ * Pass either of these to Next 16's `cacheLife(...)` inside a `'use cache'`
+ * server function. They're typed-literal exports so a typo fails at the SDK
+ * import site, not silently at runtime (Next's own `cacheLife(profile: string)`
+ * overload would accept anything and look it up as a custom profile).
+ *
+ * @example
+ * ```ts
+ * import { cacheLife } from "next/cache";
+ * import { CACHE_LIFE_DEFAULT, CACHE_LIFE_PROBE, tags } from "@cimplify/sdk/server";
+ *
+ * async function getProducts() {
+ *   "use cache";
+ *   cacheTag(tags.products());
+ *   const r = await getServerClient().catalogue.getProducts();
+ *   // Don't lock in empties / failures — a transient bad render would
+ *   // otherwise sit cached for the full "max" window.
+ *   if (!r.ok || r.value.items.length === 0) {
+ *     cacheLife(CACHE_LIFE_PROBE);
+ *     return r;
+ *   }
+ *   cacheLife(CACHE_LIFE_DEFAULT);
+ *   return r;
+ * }
+ * ```
  */
-declare function revalidateProducts(profile?: RevalidateProfile$1): Promise<void>;
 /**
- * Invalidate the cached detail of a single product (and the products list,
- * since list-shaped caches typically embed each product's denormalized
- * fields). Call after a Server Action that edits a product.
+ * The default cacheLife for cached storefront reads. Resolves to `"max"`,
+ * which is Next 16's longest built-in profile (stale 5min, revalidate 30d,
+ * never expires). Safe because Cimplify's tag-cache + CF cache-purge wiring
+ * invalidates on-demand within ~1s of a merchant edit — there's no benefit
+ * to short timer-based expirations on data Cimplify owns.
  */
+declare const CACHE_LIFE_DEFAULT: "max";
+/**
+ * Short-lived cacheLife for "probe" results — empty arrays, errors, 404s,
+ * anything that *might* be a transient bad render. Resolves to `"seconds"`
+ * (stale 30s, revalidate 1s, expires 1min). Use this when the fetch returned
+ * no usable data so a momentary backend blip can't get locked into the cache
+ * for `CACHE_LIFE_DEFAULT`'s entire window.
+ *
+ * The tag still gets attached, so a real `revalidateTag(...)` from Cimplify
+ * will refresh the entry the moment the underlying data changes.
+ */
+declare const CACHE_LIFE_PROBE: "seconds";
+/** The TS type of {@link CACHE_LIFE_DEFAULT} — the `"max"` literal. */
+type CacheLifeDefault = typeof CACHE_LIFE_DEFAULT;
+/** The TS type of {@link CACHE_LIFE_PROBE} — the `"seconds"` literal. */
+type CacheLifeProbe = typeof CACHE_LIFE_PROBE;
+
+/** Next 16 cacheLife profile — a built-in name (`'max'`/`'hours'`/…) or `{expire: secs}`. */
+type RevalidateProfile$1 = string | {
+    expire: number;
+};
+declare function revalidateProducts(profile?: RevalidateProfile$1): Promise<void>;
 declare function revalidateProduct(id: string, profile?: RevalidateProfile$1): Promise<void>;
 declare function revalidateCategories(profile?: RevalidateProfile$1): Promise<void>;
 declare function revalidateCategory(id: string, profile?: RevalidateProfile$1): Promise<void>;
@@ -114,15 +156,9 @@ declare function revalidateAddOn(id: string, profile?: RevalidateProfile$1): Pro
 declare function revalidateSubscriptions(profile?: RevalidateProfile$1): Promise<void>;
 declare function revalidateSubscription(id: string, profile?: RevalidateProfile$1): Promise<void>;
 declare function revalidateStock(productId?: string, profile?: RevalidateProfile$1): Promise<void>;
-/**
- * Escape hatch: invalidate by raw tag string. Prefer the typed helpers
- * above where possible — they keep the tag scheme in one place.
- */
 declare function revalidateByTag(tag: string, profile?: RevalidateProfile$1): Promise<void>;
 
-/** Expire the products list with read-your-writes. Call from a Server Action that creates / deletes / reorders. */
 declare function updateProducts(): Promise<void>;
-/** Expire a single product + the products list with read-your-writes. */
 declare function updateProduct(id: string): Promise<void>;
 declare function updateCategories(): Promise<void>;
 declare function updateCategory(id: string): Promise<void>;
@@ -138,25 +174,23 @@ declare function updateAddOn(id: string): Promise<void>;
 declare function updateSubscriptions(): Promise<void>;
 declare function updateSubscription(id: string): Promise<void>;
 declare function updateStock(productId?: string): Promise<void>;
-/** Escape hatch: expire a raw tag with read-your-writes. Prefer the typed helpers above. */
 declare function updateByTag(tag: string): Promise<void>;
-/**
- * Refresh uncached data on the current page (notification counts, live
- * metrics, status indicators). Server-Action-only. Complements
- * `router.refresh()` on the client.
- */
 declare function refreshPage(): Promise<void>;
 
-/** Next 16 `revalidateTag` profile arg — built-in name (`'max'`/`'hours'`/…) or inline `{expire: secs}`. */
+/** Next 16 cacheLife profile — a built-in name (`'max'`/`'hours'`/…) or `{expire: secs}`. */
 type RevalidateProfile = string | {
     expire: number;
 };
 interface RevalidateRouteOptions {
+    /** Defaults to `process.env.CIMPLIFY_REVALIDATE_SECRET`. */
     secret?: string;
+    /** Defaults to a lazy import of `next/cache.revalidateTag`. Override for tests. */
     revalidateTag?: (tag: string, profile: RevalidateProfile) => void;
+    /** Defaults to `Date.now`. Override for tests. */
     now?: () => number;
+    /** Profile used when the request body doesn't include one. Defaults to `'max'`. */
     defaultProfile?: RevalidateProfile;
 }
 declare function revalidateRouteHandler(req: Request, options?: RevalidateRouteOptions): Promise<Response>;
 
-export { CimplifyClient, type RevalidateProfile$1 as RevalidateProfile, type RevalidateRouteOptions, type RevalidateProfile as RevalidateRouteProfile, type ServerClientOptions, getServerClient, refreshPage, revalidateAddOn, revalidateAddOns, revalidateBrand, revalidateBusiness, revalidateByTag, revalidateCategories, revalidateCategory, revalidateCollection, revalidateCollections, revalidateLocation, revalidateLocations, revalidatePricing, revalidateProduct, revalidateProducts, revalidateRouteHandler, revalidateStock, revalidateSubscription, revalidateSubscriptions, tags, updateAddOn, updateAddOns, updateBrand, updateBusiness, updateByTag, updateCategories, updateCategory, updateCollection, updateCollections, updateLocation, updateLocations, updatePricing, updateProduct, updateProducts, updateStock, updateSubscription, updateSubscriptions };
+export { CACHE_LIFE_DEFAULT, CACHE_LIFE_PROBE, type CacheLifeDefault, type CacheLifeProbe, CimplifyClient, type RevalidateProfile$1 as RevalidateProfile, type RevalidateRouteOptions, type RevalidateProfile as RevalidateRouteProfile, type ServerClientOptions, getServerClient, refreshPage, revalidateAddOn, revalidateAddOns, revalidateBrand, revalidateBusiness, revalidateByTag, revalidateCategories, revalidateCategory, revalidateCollection, revalidateCollections, revalidateLocation, revalidateLocations, revalidatePricing, revalidateProduct, revalidateProducts, revalidateRouteHandler, revalidateStock, revalidateSubscription, revalidateSubscriptions, tags, updateAddOn, updateAddOns, updateBrand, updateBusiness, updateByTag, updateCategories, updateCategory, updateCollection, updateCollections, updateLocation, updateLocations, updatePricing, updateProduct, updateProducts, updateStock, updateSubscription, updateSubscriptions };

package/dist/server.d.ts

@@ -84,21 +84,63 @@ declare const tags: {
     readonly order: (id: string) => string;
 };
 
-/** Next 16 `revalidateTag` profile arg — built-in name (`'max'`/`'hours'`/…) or `{expire: secs}`. */
-type RevalidateProfile$1 = string | {
-    expire: number;
-};
 /**
- * Invalidate every cache entry tagged with the products list. Call after a
- * Server Action that creates / deletes / reorders products. The optional
- * `profile` is the Next 16 cacheLife profile (defaults to `'max'` SWR).
+ * Cimplify's opinionated cacheLife profiles for storefront server caches.
+ *
+ * Pass either of these to Next 16's `cacheLife(...)` inside a `'use cache'`
+ * server function. They're typed-literal exports so a typo fails at the SDK
+ * import site, not silently at runtime (Next's own `cacheLife(profile: string)`
+ * overload would accept anything and look it up as a custom profile).
+ *
+ * @example
+ * ```ts
+ * import { cacheLife } from "next/cache";
+ * import { CACHE_LIFE_DEFAULT, CACHE_LIFE_PROBE, tags } from "@cimplify/sdk/server";
+ *
+ * async function getProducts() {
+ *   "use cache";
+ *   cacheTag(tags.products());
+ *   const r = await getServerClient().catalogue.getProducts();
+ *   // Don't lock in empties / failures — a transient bad render would
+ *   // otherwise sit cached for the full "max" window.
+ *   if (!r.ok || r.value.items.length === 0) {
+ *     cacheLife(CACHE_LIFE_PROBE);
+ *     return r;
+ *   }
+ *   cacheLife(CACHE_LIFE_DEFAULT);
+ *   return r;
+ * }
+ * ```
  */
-declare function revalidateProducts(profile?: RevalidateProfile$1): Promise<void>;
 /**
- * Invalidate the cached detail of a single product (and the products list,
- * since list-shaped caches typically embed each product's denormalized
- * fields). Call after a Server Action that edits a product.
+ * The default cacheLife for cached storefront reads. Resolves to `"max"`,
+ * which is Next 16's longest built-in profile (stale 5min, revalidate 30d,
+ * never expires). Safe because Cimplify's tag-cache + CF cache-purge wiring
+ * invalidates on-demand within ~1s of a merchant edit — there's no benefit
+ * to short timer-based expirations on data Cimplify owns.
  */
+declare const CACHE_LIFE_DEFAULT: "max";
+/**
+ * Short-lived cacheLife for "probe" results — empty arrays, errors, 404s,
+ * anything that *might* be a transient bad render. Resolves to `"seconds"`
+ * (stale 30s, revalidate 1s, expires 1min). Use this when the fetch returned
+ * no usable data so a momentary backend blip can't get locked into the cache
+ * for `CACHE_LIFE_DEFAULT`'s entire window.
+ *
+ * The tag still gets attached, so a real `revalidateTag(...)` from Cimplify
+ * will refresh the entry the moment the underlying data changes.
+ */
+declare const CACHE_LIFE_PROBE: "seconds";
+/** The TS type of {@link CACHE_LIFE_DEFAULT} — the `"max"` literal. */
+type CacheLifeDefault = typeof CACHE_LIFE_DEFAULT;
+/** The TS type of {@link CACHE_LIFE_PROBE} — the `"seconds"` literal. */
+type CacheLifeProbe = typeof CACHE_LIFE_PROBE;
+
+/** Next 16 cacheLife profile — a built-in name (`'max'`/`'hours'`/…) or `{expire: secs}`. */
+type RevalidateProfile$1 = string | {
+    expire: number;
+};
+declare function revalidateProducts(profile?: RevalidateProfile$1): Promise<void>;
 declare function revalidateProduct(id: string, profile?: RevalidateProfile$1): Promise<void>;
 declare function revalidateCategories(profile?: RevalidateProfile$1): Promise<void>;
 declare function revalidateCategory(id: string, profile?: RevalidateProfile$1): Promise<void>;
@@ -114,15 +156,9 @@ declare function revalidateAddOn(id: string, profile?: RevalidateProfile$1): Pro
 declare function revalidateSubscriptions(profile?: RevalidateProfile$1): Promise<void>;
 declare function revalidateSubscription(id: string, profile?: RevalidateProfile$1): Promise<void>;
 declare function revalidateStock(productId?: string, profile?: RevalidateProfile$1): Promise<void>;
-/**
- * Escape hatch: invalidate by raw tag string. Prefer the typed helpers
- * above where possible — they keep the tag scheme in one place.
- */
 declare function revalidateByTag(tag: string, profile?: RevalidateProfile$1): Promise<void>;
 
-/** Expire the products list with read-your-writes. Call from a Server Action that creates / deletes / reorders. */
 declare function updateProducts(): Promise<void>;
-/** Expire a single product + the products list with read-your-writes. */
 declare function updateProduct(id: string): Promise<void>;
 declare function updateCategories(): Promise<void>;
 declare function updateCategory(id: string): Promise<void>;
@@ -138,25 +174,23 @@ declare function updateAddOn(id: string): Promise<void>;
 declare function updateSubscriptions(): Promise<void>;
 declare function updateSubscription(id: string): Promise<void>;
 declare function updateStock(productId?: string): Promise<void>;
-/** Escape hatch: expire a raw tag with read-your-writes. Prefer the typed helpers above. */
 declare function updateByTag(tag: string): Promise<void>;
-/**
- * Refresh uncached data on the current page (notification counts, live
- * metrics, status indicators). Server-Action-only. Complements
- * `router.refresh()` on the client.
- */
 declare function refreshPage(): Promise<void>;
 
-/** Next 16 `revalidateTag` profile arg — built-in name (`'max'`/`'hours'`/…) or inline `{expire: secs}`. */
+/** Next 16 cacheLife profile — a built-in name (`'max'`/`'hours'`/…) or `{expire: secs}`. */
 type RevalidateProfile = string | {
     expire: number;
 };
 interface RevalidateRouteOptions {
+    /** Defaults to `process.env.CIMPLIFY_REVALIDATE_SECRET`. */
     secret?: string;
+    /** Defaults to a lazy import of `next/cache.revalidateTag`. Override for tests. */
     revalidateTag?: (tag: string, profile: RevalidateProfile) => void;
+    /** Defaults to `Date.now`. Override for tests. */
     now?: () => number;
+    /** Profile used when the request body doesn't include one. Defaults to `'max'`. */
     defaultProfile?: RevalidateProfile;
 }
 declare function revalidateRouteHandler(req: Request, options?: RevalidateRouteOptions): Promise<Response>;
 
-export { CimplifyClient, type RevalidateProfile$1 as RevalidateProfile, type RevalidateRouteOptions, type RevalidateProfile as RevalidateRouteProfile, type ServerClientOptions, getServerClient, refreshPage, revalidateAddOn, revalidateAddOns, revalidateBrand, revalidateBusiness, revalidateByTag, revalidateCategories, revalidateCategory, revalidateCollection, revalidateCollections, revalidateLocation, revalidateLocations, revalidatePricing, revalidateProduct, revalidateProducts, revalidateRouteHandler, revalidateStock, revalidateSubscription, revalidateSubscriptions, tags, updateAddOn, updateAddOns, updateBrand, updateBusiness, updateByTag, updateCategories, updateCategory, updateCollection, updateCollections, updateLocation, updateLocations, updatePricing, updateProduct, updateProducts, updateStock, updateSubscription, updateSubscriptions };
+export { CACHE_LIFE_DEFAULT, CACHE_LIFE_PROBE, type CacheLifeDefault, type CacheLifeProbe, CimplifyClient, type RevalidateProfile$1 as RevalidateProfile, type RevalidateRouteOptions, type RevalidateProfile as RevalidateRouteProfile, type ServerClientOptions, getServerClient, refreshPage, revalidateAddOn, revalidateAddOns, revalidateBrand, revalidateBusiness, revalidateByTag, revalidateCategories, revalidateCategory, revalidateCollection, revalidateCollections, revalidateLocation, revalidateLocations, revalidatePricing, revalidateProduct, revalidateProducts, revalidateRouteHandler, revalidateStock, revalidateSubscription, revalidateSubscriptions, tags, updateAddOn, updateAddOns, updateBrand, updateBusiness, updateByTag, updateCategories, updateCategory, updateCollection, updateCollections, updateLocation, updateLocations, updatePricing, updateProduct, updateProducts, updateStock, updateSubscription, updateSubscriptions };

package/dist/server.js

@@ -6,7 +6,12 @@ require('./chunk-6RP6OPYO.js');
 var chunkTKOTACKZ_js = require('./chunk-TKOTACKZ.js');
 var react = require('react');
 
+var DEFAULT_PROD_URL = "https://storefronts.cimplify.io";
 var DEFAULT_DEV_URL = "http://127.0.0.1:8787";
+function defaultBaseUrl() {
+  const proc = globalThis.process;
+  return proc?.env?.NODE_ENV === "production" ? DEFAULT_PROD_URL : DEFAULT_DEV_URL;
+}
 function readEnv(...keys) {
   const env = globalThis.process?.env;
   if (!env) return void 0;
@@ -17,7 +22,7 @@ function readEnv(...keys) {
   return void 0;
 }
 var getServerClient = react.cache((opts = {}) => {
-  const baseUrl = opts.apiUrl ?? readEnv("CIMPLIFY_API_URL", "NEXT_PUBLIC_CIMPLIFY_API_URL") ?? DEFAULT_DEV_URL;
+  const baseUrl = opts.apiUrl ?? readEnv("CIMPLIFY_API_URL", "NEXT_PUBLIC_CIMPLIFY_API_URL") ?? defaultBaseUrl();
   const publicKey = opts.secretKey ?? readEnv("CIMPLIFY_SECRET_KEY", "NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY") ?? "mock-dev";
   const client = chunkCYGLTD7D_js.createCimplifyClient({
     baseUrl,
@@ -58,8 +63,12 @@ var tags = {
   order: (id) => `cimplify:order:${id}`
 };
 
+// src/server/cache-life.ts
+var CACHE_LIFE_DEFAULT = "max";
+var CACHE_LIFE_PROBE = "seconds";
+
 // src/server/revalidate.ts
-var DEFAULT_PROFILE = "max";
+var DEFAULT_PROFILE = CACHE_LIFE_DEFAULT;
 var _revalidateTag = null;
 async function getRevalidateTag() {
   if (_revalidateTag) return _revalidateTag;
@@ -230,7 +239,7 @@ var SIGNATURE_HEADER = "x-cimplify-signature";
 var SIGNATURE_PREFIX = "sha256=";
 var MAX_SKEW_MS = 5 * 60 * 1e3;
 var SECRET_ENV = "CIMPLIFY_REVALIDATE_SECRET";
-var DEFAULT_PROFILE2 = "max";
+var DEFAULT_PROFILE2 = CACHE_LIFE_DEFAULT;
 async function revalidateRouteHandler(req, options = {}) {
   const secret = options.secret ?? envSecret();
   if (!secret) return text(`revalidate disabled: ${SECRET_ENV} not set`, 500);
@@ -313,6 +322,8 @@ Object.defineProperty(exports, "CimplifyError", {
   enumerable: true,
   get: function () { return chunkTKOTACKZ_js.CimplifyError; }
 });
+exports.CACHE_LIFE_DEFAULT = CACHE_LIFE_DEFAULT;
+exports.CACHE_LIFE_PROBE = CACHE_LIFE_PROBE;
 exports.getServerClient = getServerClient;
 exports.refreshPage = refreshPage;
 exports.revalidateAddOn = revalidateAddOn;

package/dist/server.mjs

@@ -4,7 +4,12 @@ import './chunk-XY2DFX5K.mjs';
 export { CimplifyError } from './chunk-Z2AYLZDF.mjs';
 import { cache } from 'react';
 
+var DEFAULT_PROD_URL = "https://storefronts.cimplify.io";
 var DEFAULT_DEV_URL = "http://127.0.0.1:8787";
+function defaultBaseUrl() {
+  const proc = globalThis.process;
+  return proc?.env?.NODE_ENV === "production" ? DEFAULT_PROD_URL : DEFAULT_DEV_URL;
+}
 function readEnv(...keys) {
   const env = globalThis.process?.env;
   if (!env) return void 0;
@@ -15,7 +20,7 @@ function readEnv(...keys) {
   return void 0;
 }
 var getServerClient = cache((opts = {}) => {
-  const baseUrl = opts.apiUrl ?? readEnv("CIMPLIFY_API_URL", "NEXT_PUBLIC_CIMPLIFY_API_URL") ?? DEFAULT_DEV_URL;
+  const baseUrl = opts.apiUrl ?? readEnv("CIMPLIFY_API_URL", "NEXT_PUBLIC_CIMPLIFY_API_URL") ?? defaultBaseUrl();
   const publicKey = opts.secretKey ?? readEnv("CIMPLIFY_SECRET_KEY", "NEXT_PUBLIC_CIMPLIFY_PUBLIC_KEY") ?? "mock-dev";
   const client = createCimplifyClient({
     baseUrl,
@@ -56,8 +61,12 @@ var tags = {
   order: (id) => `cimplify:order:${id}`
 };
 
+// src/server/cache-life.ts
+var CACHE_LIFE_DEFAULT = "max";
+var CACHE_LIFE_PROBE = "seconds";
+
 // src/server/revalidate.ts
-var DEFAULT_PROFILE = "max";
+var DEFAULT_PROFILE = CACHE_LIFE_DEFAULT;
 var _revalidateTag = null;
 async function getRevalidateTag() {
   if (_revalidateTag) return _revalidateTag;
@@ -228,7 +237,7 @@ var SIGNATURE_HEADER = "x-cimplify-signature";
 var SIGNATURE_PREFIX = "sha256=";
 var MAX_SKEW_MS = 5 * 60 * 1e3;
 var SECRET_ENV = "CIMPLIFY_REVALIDATE_SECRET";
-var DEFAULT_PROFILE2 = "max";
+var DEFAULT_PROFILE2 = CACHE_LIFE_DEFAULT;
 async function revalidateRouteHandler(req, options = {}) {
   const secret = options.secret ?? envSecret();
   if (!secret) return text(`revalidate disabled: ${SECRET_ENV} not set`, 500);
@@ -307,4 +316,4 @@ function text(message, status) {
   return new Response(message, { status, headers: { "content-type": "text/plain" } });
 }
 
-export { getServerClient, refreshPage, revalidateAddOn, revalidateAddOns, revalidateBrand, revalidateBusiness, revalidateByTag, revalidateCategories, revalidateCategory, revalidateCollection, revalidateCollections, revalidateLocation, revalidateLocations, revalidatePricing, revalidateProduct, revalidateProducts, revalidateRouteHandler, revalidateStock, revalidateSubscription, revalidateSubscriptions, tags, updateAddOn, updateAddOns, updateBrand, updateBusiness, updateByTag, updateCategories, updateCategory, updateCollection, updateCollections, updateLocation, updateLocations, updatePricing, updateProduct, updateProducts, updateStock, updateSubscription, updateSubscriptions };
+export { CACHE_LIFE_DEFAULT, CACHE_LIFE_PROBE, getServerClient, refreshPage, revalidateAddOn, revalidateAddOns, revalidateBrand, revalidateBusiness, revalidateByTag, revalidateCategories, revalidateCategory, revalidateCollection, revalidateCollections, revalidateLocation, revalidateLocations, revalidatePricing, revalidateProduct, revalidateProducts, revalidateRouteHandler, revalidateStock, revalidateSubscription, revalidateSubscriptions, tags, updateAddOn, updateAddOns, updateBrand, updateBusiness, updateByTag, updateCategories, updateCategory, updateCollection, updateCollections, updateLocation, updateLocations, updatePricing, updateProduct, updateProducts, updateStock, updateSubscription, updateSubscriptions };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cimplify/sdk",
-  "version": "0.49.1",
+  "version": "0.49.2",
   "description": "Cimplify Commerce SDK for storefronts",
   "keywords": [
     "cimplify",