@01.software/sdk 0.33.0 → 0.35.0

package/dist/server.js

@@ -1,7 +1,7 @@
 // src/core/collection/http-client.ts
 import { stringify } from "qs-esm";
 
-// src/core/internal/errors/index.ts
+// src/core/errors.ts
 var SDKError = class extends Error {
   constructor(code, message, status, details, userMessage, suggestion, requestId) {
     super(message);
@@ -191,9 +191,12 @@ function resolveApiUrl(apiUrl) {
 
 // src/core/internal/utils/http.ts
 var DEFAULT_TIMEOUT = 3e4;
+var STOREFRONT_BROWSER_TIMEOUT = 15e3;
 var DEFAULT_RETRYABLE_STATUSES = [408, 429, 500, 502, 503, 504];
 var NON_RETRYABLE_STATUSES = [400, 401, 403, 404, 409, 422];
 var SAFE_METHODS = ["GET", "HEAD", "OPTIONS"];
+var DEFAULT_MAX_RETRIES = 3;
+var STOREFRONT_BROWSER_MAX_RETRIES = 1;
 function debugLog(debug, type, message, data) {
   if (!debug) return;
   const shouldLog = debug === true || type === "request" && debug.logRequests || type === "response" && debug.logResponses || type === "error" && debug.logErrors;
@@ -386,15 +389,18 @@ async function httpFetch(url, options) {
     publishableKey,
     secretKey,
     customerToken,
-    timeout = DEFAULT_TIMEOUT,
+    timeout: timeoutOption = DEFAULT_TIMEOUT,
     debug,
     retry,
     onUnauthorized,
     ...requestInit
   } = options || {};
   const baseUrl = resolveApiUrl(apiUrl);
+  const method = (requestInit.method || "GET").toUpperCase();
+  const isPublishableKeyBrowserGet = typeof window !== "undefined" && !secretKey && !customerToken && Boolean(publishableKey) && SAFE_METHODS.includes(method);
+  const timeout = timeoutOption === DEFAULT_TIMEOUT && isPublishableKeyBrowserGet ? STOREFRONT_BROWSER_TIMEOUT : timeoutOption;
   const retryConfig = {
-    maxRetries: retry?.maxRetries ?? 3,
+    maxRetries: retry?.maxRetries ?? (isPublishableKeyBrowserGet ? STOREFRONT_BROWSER_MAX_RETRIES : DEFAULT_MAX_RETRIES),
     retryableStatuses: retry?.retryableStatuses ?? DEFAULT_RETRYABLE_STATUSES,
     retryDelay: retry?.retryDelay ?? ((attempt) => Math.min(1e3 * 2 ** attempt, 1e4))
   };
@@ -502,8 +508,8 @@ async function httpFetch(url, options) {
           ),
           requestId
         );
-        const method = (requestInit.method || "GET").toUpperCase();
-        if (attempt < retryConfig.maxRetries && SAFE_METHODS.includes(method) && retryConfig.retryableStatuses.includes(response.status)) {
+        const method2 = (requestInit.method || "GET").toUpperCase();
+        if (attempt < retryConfig.maxRetries && SAFE_METHODS.includes(method2) && retryConfig.retryableStatuses.includes(response.status)) {
           lastError = error;
           const retryDelay = retryConfig.retryDelay(attempt);
           debugLog(debug, "error", `Retrying in ${retryDelay}ms...`, error);
@@ -515,8 +521,8 @@ async function httpFetch(url, options) {
       return response;
     } catch (error) {
       debugLog(debug, "error", url, error);
-      const method = (requestInit.method || "GET").toUpperCase();
-      const isSafe = SAFE_METHODS.includes(method);
+      const method2 = (requestInit.method || "GET").toUpperCase();
+      const isSafe = SAFE_METHODS.includes(method2);
       if (error instanceof Error && error.name === "AbortError") {
         const timeoutError = createTimeoutError(
           `Request timed out after ${timeout}ms.`,
@@ -575,6 +581,35 @@ async function httpFetch(url, options) {
   throw lastError ?? new NetworkError("Request failed after retries");
 }
 
+// src/core/internal/utils/query-string.ts
+function productDetailQuery(params) {
+  const search = new URLSearchParams();
+  if ("slug" in params) {
+    search.set("slug", params.slug);
+  } else {
+    search.set("id", params.id);
+  }
+  return `/api/products/detail?${search}`;
+}
+function productDetailCatalogQuery(params) {
+  const search = new URLSearchParams();
+  if ("slug" in params) {
+    search.set("slug", params.slug);
+  } else {
+    search.set("id", params.id);
+  }
+  return `/api/products/detail/catalog?${search}`;
+}
+function listingGroupsQuery(params) {
+  return `/api/products/listing-groups?ids=${params.productIds.map(encodeURIComponent).join(",")}`;
+}
+function listingGroupsCatalogQuery(params) {
+  return `/api/products/listing-groups/catalog?ids=${params.productIds.map(encodeURIComponent).join(",")}`;
+}
+function stockSnapshotQuery(params) {
+  return `/api/products/stock?variantIds=${params.variantIds.map(encodeURIComponent).join(",")}`;
+}
+
 // src/core/collection/http-client.ts
 var HttpClient = class {
   constructor(publishableKey, secretKey, getCustomerToken, onUnauthorized, onRequestId, apiUrl) {
@@ -948,6 +983,16 @@ var CollectionClient = class extends HttpClient {
     });
     return this.parseFindResponse(response);
   }
+  /**
+   * Find-like response from a cacheable GET custom endpoint.
+   */
+  async requestFindEndpointGet(endpoint) {
+    const response = await this.fetchWithTracking(endpoint, {
+      ...this.defaultOptions,
+      method: "GET"
+    });
+    return this.parseFindResponse(response);
+  }
   /**
    * Find document by ID
    * GET /api/{collection}/{id}
@@ -1109,6 +1154,8 @@ async function parseApiResponse(response, endpoint) {
 }
 
 // src/core/community/community-client.ts
+var DEFAULT_POST_LIST_SORT = "-lastActivityAt";
+var DEFAULT_COMMENT_LIST_SORT = "-createdAt";
 var CommunityClient = class {
   constructor(options) {
     this.publishableKey = requirePublishableKeyForSecret(
@@ -1127,6 +1174,40 @@ var CommunityClient = class {
     const entries = Object.entries(params).filter((e) => e[1] !== void 0).map(([k, v]) => [k, String(v)]);
     return entries.length ? `?${new URLSearchParams(entries).toString()}` : "";
   }
+  buildPostsListQuery(params) {
+    const urlParams = new URLSearchParams();
+    const sort = params?.sort ?? DEFAULT_POST_LIST_SORT;
+    urlParams.set("sort", sort);
+    if (params?.limit !== void 0) urlParams.set("limit", String(params.limit));
+    if (params?.page !== void 0) urlParams.set("page", String(params.page));
+    if (params?.categoryId !== void 0) {
+      urlParams.set("where[categories][in]", params.categoryId);
+    }
+    if (params?.tagId !== void 0) {
+      urlParams.set("where[tags][in]", params.tagId);
+    }
+    return `/api/posts?${urlParams.toString()}`;
+  }
+  buildCommentsListQuery(params) {
+    const urlParams = new URLSearchParams();
+    const sort = params.sort ?? DEFAULT_COMMENT_LIST_SORT;
+    urlParams.set("sort", sort);
+    if (params.postId !== void 0) {
+      urlParams.set("where[post][equals]", params.postId);
+    }
+    if (params.parentId !== void 0) {
+      urlParams.set("where[parent][equals]", params.parentId);
+    }
+    if (params.rootComment !== void 0) {
+      urlParams.set("where[rootComment][equals]", params.rootComment);
+    }
+    if (params.topLevelOnly) {
+      urlParams.set("where[parent][exists]", "false");
+    }
+    if (params.limit !== void 0) urlParams.set("limit", String(params.limit));
+    if (params.page !== void 0) urlParams.set("page", String(params.page));
+    return `/api/comments?${urlParams.toString()}`;
+  }
   async execute(endpoint, method, body) {
     const token = typeof this.customerToken === "function" ? this.customerToken() : this.customerToken;
     try {
@@ -1150,6 +1231,28 @@ var CommunityClient = class {
   createPost(params) {
     return this.execute("/api/posts", "POST", params);
   }
+  /**
+   * Public post feed. Server applies the same visibility contract as
+   * `communityPostRead` (published + visible + moderation-safe).
+   */
+  listPosts(params) {
+    return this.execute(
+      this.buildPostsListQuery(params),
+      "GET"
+    );
+  }
+  listPostCategories(params) {
+    return this.execute(
+      `/api/post-categories${this.buildQuery(params)}`,
+      "GET"
+    );
+  }
+  listPostTags(params) {
+    return this.execute(
+      `/api/post-tags${this.buildQuery(params)}`,
+      "GET"
+    );
+  }
   getMyPosts(params) {
     return this.execute(
       `/api/posts/my${this.buildQuery(params)}`,
@@ -1185,16 +1288,37 @@ var CommunityClient = class {
     }
     return this.execute("/api/comments", "POST", body);
   }
+  /**
+   * List comments for a post.
+   *
+   * - Default: all visible comments on the post (any depth).
+   * - `topLevelOnly: true`: only root comments (`parent` unset).
+   * - `rootComment`: comments belonging to a thread rooted at that comment.
+   */
   listComments(params) {
-    const { postId, page, limit, rootComment } = params;
-    const urlParams = new URLSearchParams();
-    urlParams.set("where[post][equals]", postId);
-    urlParams.set("sort", "-createdAt");
-    if (limit !== void 0) urlParams.set("limit", String(limit));
-    if (page !== void 0) urlParams.set("page", String(page));
-    if (rootComment !== void 0) urlParams.set("where[rootComment][equals]", rootComment);
+    const { postId, page, limit, rootComment, topLevelOnly, sort } = params;
+    return this.execute(
+      this.buildCommentsListQuery({
+        postId,
+        page,
+        limit,
+        rootComment,
+        topLevelOnly,
+        sort
+      }),
+      "GET"
+    );
+  }
+  /** Direct replies to a comment (`where[parent][equals]`). */
+  listReplies(params) {
+    const { commentId, page, limit, sort } = params;
     return this.execute(
-      `/api/comments?${urlParams.toString()}`,
+      this.buildCommentsListQuery({
+        parentId: commentId,
+        page,
+        limit,
+        sort
+      }),
       "GET"
     );
   }
@@ -1222,10 +1346,18 @@ var CommunityClient = class {
   }
   // Reactions
   addReaction(params) {
-    const { postId, type } = params;
+    const { postId, typeSlug, type } = params;
+    const reactionType = typeSlug ?? type;
+    if (!reactionType) {
+      throw new SDKError(
+        "validation_failed",
+        "addReaction requires typeSlug (or deprecated type)",
+        400
+      );
+    }
     return this.execute("/api/reactions", "POST", {
       post: postId,
-      type
+      type: reactionType
     });
   }
   removeReaction(params) {
@@ -1236,10 +1368,18 @@ var CommunityClient = class {
     );
   }
   addCommentReaction(params) {
-    const { commentId, type } = params;
+    const { commentId, typeSlug, type } = params;
+    const reactionType = typeSlug ?? type;
+    if (!reactionType) {
+      throw new SDKError(
+        "validation_failed",
+        "addCommentReaction requires typeSlug (or deprecated type)",
+        400
+      );
+    }
     return this.execute("/api/reactions", "POST", {
       comment: commentId,
-      type
+      type: reactionType
     });
   }
   removeCommentReaction(params) {
@@ -1255,6 +1395,12 @@ var CommunityClient = class {
       "GET"
     );
   }
+  getCommentReactionSummary(params) {
+    return this.execute(
+      `/api/comments/${params.commentId}/reactions`,
+      "GET"
+    );
+  }
   getReactionTypes() {
     return this.execute(
       "/api/reaction-types?limit=100",
@@ -1279,6 +1425,25 @@ var CommunityClient = class {
       "GET"
     );
   }
+  // Profiles
+  listProfileLists(params) {
+    return this.execute(
+      `/api/customer-profile-lists${this.buildQuery(params)}`,
+      "GET"
+    );
+  }
+  async getProfileList(params) {
+    const query = "slug" in params ? `?where[slug][equals]=${encodeURIComponent(params.slug)}&limit=1` : `?where[id][equals]=${encodeURIComponent(params.id)}&limit=1`;
+    const res = await this.execute(`/api/customer-profile-lists${query}`, "GET");
+    return res.docs[0] ?? null;
+  }
+  updatePublicProfile(body) {
+    return this.execute(
+      "/api/customers/me/profile",
+      "PATCH",
+      body
+    );
+  }
 };
 
 // src/core/api/base-api.ts
@@ -1323,10 +1488,18 @@ var ModerationApi = class extends BaseApi {
     super("ModerationApi", options);
   }
   banCustomer(params) {
-    return this.request("/api/community-bans/ban", params);
+    return this.request(
+      "/api/community-bans/ban-bearer",
+      params,
+      { method: "POST" }
+    );
   }
   unbanCustomer(params) {
-    return this.request("/api/community-bans/unban", params);
+    return this.request(
+      "/api/community-bans/unban-bearer",
+      params,
+      { method: "POST" }
+    );
   }
 };
 
@@ -1423,6 +1596,37 @@ function productDetailResultFromError(error) {
   if (!reason) return void 0;
   return { found: false, reason };
 }
+function rejectLegacyOptionValueSwatchColor(value) {
+  if (Object.prototype.hasOwnProperty.call(
+    value,
+    "swatchColor"
+  )) {
+    throw new TypeError(
+      'Product upsert option values no longer accept legacy flat "swatchColor"; use nested "swatch" instead.'
+    );
+  }
+}
+function normalizeProductUpsertOptionValue(value) {
+  rejectLegacyOptionValueSwatchColor(value);
+  return value;
+}
+function normalizeProductUpsertParams(params) {
+  const options = params.options ?? [];
+  const variants = params.variants ?? [];
+  if (!options.length) {
+    return { ...params, options, variants };
+  }
+  return {
+    ...params,
+    options: options.map((option) => ({
+      ...option,
+      values: option.values.map(
+        (value) => normalizeProductUpsertOptionValue(value)
+      )
+    })),
+    variants
+  };
+}
 var ProductApi = class extends BaseApi {
   constructor(options) {
     super("ProductApi", options);
@@ -1435,10 +1639,25 @@ var ProductApi = class extends BaseApi {
   stockCheck(params) {
     return this.request("/api/products/stock-check", params);
   }
+  stockSnapshot(params) {
+    return this.request(
+      stockSnapshotQuery(params),
+      void 0,
+      { method: "GET" }
+    );
+  }
   listingGroups(params) {
     return this.request(
-      "/api/products/listing-groups",
-      params
+      listingGroupsQuery(params),
+      void 0,
+      { method: "GET" }
+    );
+  }
+  listingGroupsCatalog(params) {
+    return this.request(
+      listingGroupsCatalogQuery(params),
+      void 0,
+      { method: "GET" }
     );
   }
   /**
@@ -1454,8 +1673,9 @@ var ProductApi = class extends BaseApi {
   async detail(params) {
     try {
       const product = await this.request(
-        "/api/products/detail",
-        params
+        productDetailQuery(params),
+        void 0,
+        { method: "GET" }
       );
       return { found: true, product };
     } catch (err) {
@@ -1464,6 +1684,20 @@ var ProductApi = class extends BaseApi {
       throw err;
     }
   }
+  async detailCatalog(params) {
+    try {
+      const product = await this.request(
+        productDetailCatalogQuery(params),
+        void 0,
+        { method: "GET" }
+      );
+      return { found: true, product };
+    } catch (err) {
+      const notFoundResult = productDetailResultFromError(err);
+      if (notFoundResult?.found === false) return notFoundResult;
+      throw err;
+    }
+  }
   /**
    * Atomically create or update a product together with its options,
    * option-values, and variants in a single transaction. Mirrors Shopify's
@@ -1471,7 +1705,10 @@ var ProductApi = class extends BaseApi {
    * `product-upsert` tool.
    */
   upsert(params) {
-    return this.request("/api/products/upsert", params);
+    return this.request(
+      "/api/products/upsert",
+      normalizeProductUpsertParams(params)
+    );
   }
 };
 
@@ -1496,12 +1733,24 @@ var ShippingApi = class extends BaseApi {
 };
 
 // src/core/api/order-api.ts
+function idempotencyRequestOptions(idempotencyKey) {
+  return idempotencyKey ? { headers: { "X-Idempotency-Key": idempotencyKey } } : void 0;
+}
+function splitIdempotencyKey(params) {
+  const { idempotencyKey, ...body } = params;
+  return { body, idempotencyKey };
+}
 var OrderApi = class extends BaseApi {
   constructor(options) {
     super("OrderApi", options);
   }
   createOrder(params) {
-    return this.request("/api/orders/create", params);
+    const { body, idempotencyKey } = splitIdempotencyKey(params);
+    return this.request(
+      "/api/orders/create",
+      body,
+      idempotencyRequestOptions(idempotencyKey)
+    );
   }
   updateOrder(params) {
     return this.request("/api/orders/update", params);
@@ -1510,17 +1759,42 @@ var OrderApi = class extends BaseApi {
     return this.request("/api/transactions/update", params);
   }
   confirmPayment(params) {
+    const { body, idempotencyKey } = splitIdempotencyKey(params);
+    const headerKey = idempotencyKey ?? params.providerEventId;
     return this.request(
       "/api/orders/confirm-payment",
-      params,
-      params.providerEventId ? { headers: { "X-Idempotency-Key": params.providerEventId } } : void 0
+      body,
+      idempotencyRequestOptions(headerKey)
+    );
+  }
+  cancelOrder(params) {
+    const { idempotencyKey } = params;
+    const body = {
+      orderNumber: params.orderNumber,
+      reasonCode: params.reasonCode,
+      reasonDetail: params.reasonDetail
+    };
+    return this.request(
+      "/api/orders/cancel",
+      body,
+      idempotencyKey ? { headers: { "X-Idempotency-Key": idempotencyKey } } : void 0
     );
   }
   checkout(params) {
-    return this.request("/api/orders/checkout", params);
+    const { body, idempotencyKey } = splitIdempotencyKey(params);
+    return this.request(
+      "/api/orders/checkout",
+      body,
+      idempotencyRequestOptions(idempotencyKey)
+    );
   }
   createFulfillment(params) {
-    return this.request("/api/orders/create-fulfillment", params);
+    const { body, idempotencyKey } = splitIdempotencyKey(params);
+    return this.request(
+      "/api/orders/create-fulfillment",
+      body,
+      idempotencyRequestOptions(idempotencyKey)
+    );
   }
   updateFulfillment(params) {
     return this.request("/api/orders/update-fulfillment", params);
@@ -1532,13 +1806,20 @@ var OrderApi = class extends BaseApi {
     );
   }
   returnWithRefund(params) {
+    const { body, idempotencyKey } = splitIdempotencyKey(params);
     return this.request(
       "/api/returns/return-refund",
-      params
+      body,
+      idempotencyRequestOptions(idempotencyKey)
     );
   }
   createReturn(params) {
-    return this.request("/api/returns/create", params);
+    const { body, idempotencyKey } = splitIdempotencyKey(params);
+    return this.request(
+      "/api/returns/create",
+      body,
+      idempotencyRequestOptions(idempotencyKey)
+    );
   }
   updateReturn(params) {
     return this.request("/api/returns/update", params);
@@ -1640,6 +1921,7 @@ var ServerCommerceClient = class {
       update: orderApi.updateOrder.bind(orderApi),
       updateTransaction: orderApi.updateTransaction.bind(orderApi),
       confirmPayment: orderApi.confirmPayment.bind(orderApi),
+      cancelOrder: orderApi.cancelOrder.bind(orderApi),
       createFulfillment: orderApi.createFulfillment.bind(orderApi),
       updateFulfillment: orderApi.updateFulfillment.bind(orderApi),
       bulkImportFulfillments: orderApi.bulkImportFulfillments.bind(orderApi),
@@ -1656,6 +1938,113 @@ var ServerCommerceClient = class {
   }
 };
 
+// src/core/events/events-client.ts
+var EventsClient = class {
+  constructor(options) {
+    const secretKey = options.secretKey;
+    this.publishableKey = requirePublishableKeyForSecret(
+      "EventsClient",
+      options.publishableKey,
+      secretKey
+    );
+    this.apiUrl = options.apiUrl;
+    this.customerToken = options.customerToken;
+    this.onUnauthorized = options.onUnauthorized;
+    this.onRequestId = options.onRequestId;
+  }
+  getRange(params) {
+    return this.execute(
+      buildRangeEndpoint(params),
+      "GET",
+      void 0,
+      { useCustomerAuth: false }
+    );
+  }
+  register(params) {
+    return this.execute(
+      "/api/event-registrations/register",
+      "POST",
+      buildRegistrationRequestBody(params),
+      { useCustomerAuth: true }
+    );
+  }
+  getGuestRegistration(token) {
+    return this.execute(
+      "/api/event-registrations/guest/lookup",
+      "POST",
+      { token },
+      { useCustomerAuth: false }
+    );
+  }
+  cancelGuestRegistration(token, params = {}) {
+    return this.execute(
+      "/api/event-registrations/guest/cancel",
+      "POST",
+      buildGuestCancelRequestBody(token, params),
+      { useCustomerAuth: false }
+    );
+  }
+  async execute(endpoint, method, body, options = {}) {
+    const useCustomerAuth = options.useCustomerAuth === true;
+    const token = useCustomerAuth ? typeof this.customerToken === "function" ? this.customerToken() : this.customerToken : void 0;
+    try {
+      const response = await httpFetch(endpoint, {
+        method,
+        apiUrl: this.apiUrl,
+        publishableKey: this.publishableKey,
+        ...useCustomerAuth && token ? { customerToken: token } : {},
+        ...useCustomerAuth && token && this.onUnauthorized && { onUnauthorized: this.onUnauthorized },
+        ...body !== void 0 && { body: JSON.stringify(body) }
+      });
+      this.onRequestId?.(response.headers.get("x-request-id") ?? null);
+      return parseApiResponse(response, endpoint);
+    } catch (err) {
+      const id = err instanceof SDKError ? err.requestId ?? null : null;
+      this.onRequestId?.(id);
+      throw err;
+    }
+  }
+};
+function buildRegistrationRequestBody(params) {
+  return {
+    event: params.event,
+    occurrence: params.occurrence,
+    ...params.quantity !== void 0 && { quantity: params.quantity },
+    ...params.attendee !== void 0 && { attendee: params.attendee },
+    ...params.answers !== void 0 && { answers: params.answers }
+  };
+}
+function buildGuestCancelRequestBody(token, params) {
+  return {
+    token,
+    ...params.reason !== void 0 && { reason: params.reason }
+  };
+}
+function buildRangeEndpoint(params) {
+  const urlParams = new URLSearchParams();
+  urlParams.set("start", formatDateParam(params.start));
+  urlParams.set("end", formatDateParam(params.end));
+  if (params.limit !== void 0) urlParams.set("limit", String(params.limit));
+  if (params.page !== void 0) urlParams.set("page", String(params.page));
+  appendValues(urlParams, "calendar", params.calendar);
+  appendValues(urlParams, "calendarSlug", params.calendarSlug);
+  appendValues(urlParams, "category", params.category);
+  appendValues(urlParams, "categorySlug", params.categorySlug);
+  appendValues(urlParams, "tag", params.tag);
+  appendValues(urlParams, "tagSlug", params.tagSlug);
+  return `/api/event-occurrences/range?${urlParams.toString()}`;
+}
+function formatDateParam(value) {
+  return value instanceof Date ? value.toISOString() : value;
+}
+function appendValues(params, key, value) {
+  if (value === void 0) return;
+  const values = Array.isArray(value) ? value : [value];
+  for (const entry of values) {
+    if (entry) params.append(key, entry);
+  }
+}
+
 // src/core/api/tenant-introspection-api.ts
 var TenantIntrospectionApi = class extends BaseApi {
   constructor(options) {
@@ -1742,6 +2131,23 @@ var ServerClient = class {
       this.config.apiUrl
     );
   }
+  get events() {
+    if (!this._events) {
+      if (!this.config.publishableKey) {
+        throw createConfigError(
+          "publishableKey is required for server.events. It is sent as X-Publishable-Key for rate limiting and quota enforcement. Get it from Console > Settings > API Keys."
+        );
+      }
+      this._events = new EventsClient({
+        publishableKey: this.config.publishableKey,
+        apiUrl: this.config.apiUrl,
+        onRequestId: (id) => {
+          this.lastRequestId = id;
+        }
+      });
+    }
+    return this._events;
+  }
   getState() {
     return { ...this.state };
   }
@@ -1756,6 +2162,7 @@ function createServerClient(options) {
 export {
   CollectionClient,
   CommunityClient,
+  EventsClient,
   ModerationApi,
   ServerClient,
   ServerCollectionClient,