@shopkit/data-layer 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -257,7 +257,7 @@ interface ICollectionQueryRequest {
257
257
  }
258
258
 
259
259
  // Get multiple collections by handles with individual query parameters
260
- getCollectionsByHandels(params: ICollectionsByhandlesRequest, options?: IOptionsRequest): Promise<IResponse>
260
+ getCollectionsByHandles(params: ICollectionsByhandlesRequest, options?: IOptionsRequest): Promise<IResponse>
261
261
 
262
262
  interface ICollectionsByhandlesRequest {
263
263
  handles: string[];
@@ -506,16 +506,23 @@ interface IArticleByHandleRequest {
506
506
 
507
507
  ```typescript
508
508
  // Custom GraphQL request (Shopify only)
509
- graphqlRequest(query: string, variables?: Record<string, any>): Promise<IResponse>
509
+ graphqlRequest(params: IGraphqlRequest): Promise<IResponse>
510
+
511
+ interface IGraphqlRequest {
512
+ query: string;
513
+ variables?: Record<string, any>;
514
+ }
510
515
 
511
516
  // Custom HTTP fetch request
512
- fetchRequest(url: string, options?: IFetchOptionsRequest): Promise<IResponse>
517
+ fetchRequest(params: IFetchRequest): Promise<IResponse>
513
518
 
514
- interface IFetchOptionsRequest {
519
+ interface IFetchRequest {
520
+ url: string;
515
521
  method?: string;
516
522
  headers?: Record<string, string>;
517
523
  body?: string;
518
- params?: Record<string, string>;
524
+ signal?: AbortSignal;
525
+ [key: string]: any;
519
526
  }
520
527
  ```
521
528
 
@@ -556,7 +563,7 @@ const collection = await client.getCollection({ handle: "collection-handle" });
556
563
  const collections = await client.getCollections({ first: 10 });
557
564
 
558
565
  // Get collections by handles with shared parameters
559
- const collections = await client.getCollectionsByHandels({
566
+ const collections = await client.getCollectionsByHandles({
560
567
  handles: ["featured-products", "sale-items", "new-arrivals"],
561
568
  first: 10,
562
569
  productLimit: 20,
@@ -739,7 +746,7 @@ export function useProducts(query?: string) {
739
746
  | **Collection Operations** |
740
747
  | `getCollection` | ✅ Implemented | ✅ Implemented | Single collection retrieval |
741
748
  | `getCollections` | ✅ Implemented | ✅ Implemented | Collection listing |
742
- | `getCollectionsByHandels` | ✅ Implemented | ✅ Implemented | Batch collection retrieval |
749
+ | `getCollectionsByHandles` | ✅ Implemented | ✅ Implemented | Batch collection retrieval |
743
750
  | **Order Operations** |
744
751
  | `getOrder` | ❌ (Error thrown) | ❌ (NotImplemented) | Single order retrieval |
745
752
  | `getOrders` | ❌ (Error thrown) | ❌ (NotImplemented) | Order listing |
@@ -1,4 +1,4 @@
1
- import { I as IShopifyConfig, S as ShopifyCommerceClient, a as ICustomConfig, C as CustomBackendClient } from '../service-NPmqCNGb.mjs';
1
+ import { I as IShopifyConfig, S as ShopifyCommerceClient, a as ICustomConfig, C as CustomBackendClient } from '../service-Cnm8tn7H.mjs';
2
2
  import '../models/index.mjs';
3
3
 
4
4
  /**
@@ -1,4 +1,4 @@
1
- import { I as IShopifyConfig, S as ShopifyCommerceClient, a as ICustomConfig, C as CustomBackendClient } from '../service-Q7zlmyFk.js';
1
+ import { I as IShopifyConfig, S as ShopifyCommerceClient, a as ICustomConfig, C as CustomBackendClient } from '../service-Dw9qj17-.js';
2
2
  import '../models/index.js';
3
3
 
4
4
  /**
@@ -850,14 +850,25 @@ var BaseCommerceClient = class {
850
850
  }
851
851
  /**
852
852
  * Retrieve multiple products by their handles
853
- * @param handles - Array of product handles
853
+ * @param params - Object containing array of product handles
854
854
  * @param options - Request options (headers, timeout, etc.)
855
855
  * @returns Promise resolving to array of products
856
856
  * @throws NotImplementedError if not implemented in adapter
857
857
  */
858
- getProductsByHandles(handles, options) {
858
+ getProductsByHandles(params, options) {
859
859
  this.throwNotImplemented("getProductsByHandles");
860
860
  }
861
+ /**
862
+ * Retrieve product recommendations for a given product
863
+ * Uses platform-specific recommendation algorithms (e.g., Shopify's productRecommendations)
864
+ * @param productId - Product ID or handle to get recommendations for
865
+ * @param options - Request options (headers, timeout, etc.)
866
+ * @returns Promise resolving to array of recommended products
867
+ * @throws NotImplementedError if not implemented in adapter
868
+ */
869
+ getProductRecommendations(params, options) {
870
+ this.throwNotImplemented("getProductRecommendations");
871
+ }
861
872
  // ========================================
862
873
  // COLLECTION OPERATIONS
863
874
  // ========================================
@@ -899,8 +910,8 @@ var BaseCommerceClient = class {
899
910
  * @returns Promise resolving to collections data with individual query results
900
911
  * @throws NotImplementedError if not implemented in adapter
901
912
  */
902
- getCollectionsByHandels(params, options) {
903
- this.throwNotImplemented("getCollectionsByHandels");
913
+ getCollectionsByHandles(params, options) {
914
+ this.throwNotImplemented("getCollectionsByHandles");
904
915
  }
905
916
  /**
906
917
  * Retrieve available filters for collections
@@ -937,12 +948,12 @@ var BaseCommerceClient = class {
937
948
  }
938
949
  /**
939
950
  * Create a new order
940
- * @param data - Order data to create
951
+ * @param params - Order data to create
941
952
  * @param options - Request options (headers, timeout, etc.)
942
953
  * @returns Promise resolving to created order
943
954
  * @throws NotImplementedError if not implemented in adapter
944
955
  */
945
- createOrder(data, options) {
956
+ createOrder(params, options) {
946
957
  this.throwNotImplemented("createOrder");
947
958
  }
948
959
  /**
@@ -1000,12 +1011,12 @@ var BaseCommerceClient = class {
1000
1011
  }
1001
1012
  /**
1002
1013
  * Create a new customer account
1003
- * @param data - Customer data to create
1014
+ * @param params - Customer data to create
1004
1015
  * @param options - Request options (headers, timeout, etc.)
1005
1016
  * @returns Promise resolving to created customer
1006
1017
  * @throws NotImplementedError if not implemented in adapter
1007
1018
  */
1008
- createCustomer(data, options) {
1019
+ createCustomer(params, options) {
1009
1020
  this.throwNotImplemented("createCustomer");
1010
1021
  }
1011
1022
  /**
@@ -1083,28 +1094,6 @@ var BaseCommerceClient = class {
1083
1094
  createCheckout(params, options) {
1084
1095
  this.throwNotImplemented("createCheckout");
1085
1096
  }
1086
- /**
1087
- * Update an existing checkout session
1088
- * @param id - Checkout identifier
1089
- * @param data - Checkout update data
1090
- * @param options - Request options (headers, timeout, etc.)
1091
- * @returns Promise resolving to updated checkout
1092
- * @throws NotImplementedError if not implemented in adapter
1093
- */
1094
- updateCheckout(id, data, options) {
1095
- this.throwNotImplemented("updateCheckout");
1096
- }
1097
- /**
1098
- * Complete a checkout and create an order
1099
- * @param id - Checkout identifier
1100
- * @param paymentData - Payment information
1101
- * @param options - Request options (headers, timeout, etc.)
1102
- * @returns Promise resolving to created order
1103
- * @throws NotImplementedError if not implemented in adapter
1104
- */
1105
- completeCheckout(id, paymentData, options) {
1106
- this.throwNotImplemented("completeCheckout");
1107
- }
1108
1097
  // ========================================
1109
1098
  // ARTICLE/BLOG OPERATIONS
1110
1099
  // ========================================
@@ -1153,22 +1142,21 @@ var BaseCommerceClient = class {
1153
1142
  // ========================================
1154
1143
  /**
1155
1144
  * Utility method to make GraphQL requests
1156
- * @param query - GraphQL query string
1157
- * @param variables - GraphQL variables
1145
+ * @param params - Object containing query string and optional variables
1158
1146
  * @returns Promise resolving to standardized response
1159
1147
  * @throws NotImplementedError if not implemented in adapter
1160
1148
  */
1161
- graphqlRequest(query, variables) {
1149
+ graphqlRequest(params) {
1162
1150
  this.throwNotImplemented("graphqlRequest");
1163
1151
  }
1164
1152
  /**
1165
1153
  * Utility method to make custom fetch requests to any endpoint
1166
- * @param url - Target URL for the request
1167
- * @param options - Request options
1154
+ * @param params - Object containing url and optional fetch options
1168
1155
  * @returns Promise resolving to standardized response
1169
1156
  */
1170
- async fetchRequest(url, fetchOptions) {
1157
+ async fetchRequest(params) {
1171
1158
  try {
1159
+ const { url, ...fetchOptions } = params;
1172
1160
  const response = await fetch(url, fetchOptions);
1173
1161
  const data = await response.json();
1174
1162
  if (response.ok) {
@@ -1626,6 +1614,92 @@ var GET_COLLECTION = `
1626
1614
  }
1627
1615
  }
1628
1616
  `;
1617
+ var GET_PRODUCT_RECOMMENDATIONS = `
1618
+ query GetProductRecommendations($productId: ID!) {
1619
+ productRecommendations(productId: $productId) {
1620
+ id
1621
+ title
1622
+ description
1623
+ handle
1624
+ productType
1625
+ vendor
1626
+ tags
1627
+ availableForSale
1628
+ options {
1629
+ id
1630
+ name
1631
+ values
1632
+ }
1633
+ variants(first: 10) {
1634
+ nodes {
1635
+ id
1636
+ title
1637
+ sku
1638
+ availableForSale
1639
+ selectedOptions {
1640
+ name
1641
+ value
1642
+ }
1643
+ price {
1644
+ amount
1645
+ currencyCode
1646
+ }
1647
+ compareAtPrice {
1648
+ amount
1649
+ currencyCode
1650
+ }
1651
+ image {
1652
+ id
1653
+ url
1654
+ altText
1655
+ width
1656
+ height
1657
+ }
1658
+ }
1659
+ }
1660
+ images(first: 10) {
1661
+ nodes {
1662
+ id
1663
+ url
1664
+ altText
1665
+ width
1666
+ height
1667
+ }
1668
+ }
1669
+ priceRange {
1670
+ minVariantPrice {
1671
+ amount
1672
+ currencyCode
1673
+ }
1674
+ maxVariantPrice {
1675
+ amount
1676
+ currencyCode
1677
+ }
1678
+ }
1679
+ compareAtPriceRange {
1680
+ minVariantPrice {
1681
+ amount
1682
+ currencyCode
1683
+ }
1684
+ maxVariantPrice {
1685
+ amount
1686
+ currencyCode
1687
+ }
1688
+ }
1689
+ metafields(
1690
+ identifiers: [
1691
+ { namespace: "reviews", key: "rating" },
1692
+ { namespace: "reviews", key: "rating_count" }
1693
+ ]
1694
+ ) {
1695
+ key
1696
+ namespace
1697
+ value
1698
+ type
1699
+ }
1700
+ }
1701
+ }
1702
+ `;
1629
1703
  var GET_COLLECTIONS = `
1630
1704
  query GetCollections(
1631
1705
  $first: Int,
@@ -1852,11 +1926,78 @@ var ProductService = class extends BaseShopifyService {
1852
1926
  });
1853
1927
  }
1854
1928
  }
1929
+ /**
1930
+ * Get product recommendations for a given product
1931
+ * Uses Shopify's productRecommendations API
1932
+ */
1933
+ async getProductRecommendations(params, options) {
1934
+ try {
1935
+ const { productId } = params;
1936
+ if (!productId) {
1937
+ return formatResponse({
1938
+ success: false,
1939
+ message: "No product ID provided."
1940
+ });
1941
+ }
1942
+ const formattedId = productId.includes("gid://") ? productId : `gid://shopify/Product/${productId}`;
1943
+ const query = options?.query || GET_PRODUCT_RECOMMENDATIONS;
1944
+ const variables = options?.variables || { productId: formattedId };
1945
+ const { result, errors } = await this.query(query, variables, options);
1946
+ if (errors && errors.length > 0) {
1947
+ this.logger.error(
1948
+ "GraphQL errors in GET_PRODUCT_RECOMMENDATIONS",
1949
+ void 0,
1950
+ { errors }
1951
+ );
1952
+ return formatResponse({
1953
+ success: false,
1954
+ message: "Failed to fetch product recommendations due to upstream errors.",
1955
+ error: {
1956
+ message: "GraphQL errors received.",
1957
+ details: errors
1958
+ }
1959
+ });
1960
+ }
1961
+ if (!result.data || !result.data.productRecommendations) {
1962
+ return formatResponse({
1963
+ success: true,
1964
+ message: "No product recommendations found.",
1965
+ data: [],
1966
+ meta: void 0
1967
+ });
1968
+ }
1969
+ return formatResponse({
1970
+ success: true,
1971
+ message: "Product recommendations retrieved successfully.",
1972
+ data: mapGetProductsToResponse({
1973
+ nodes: result.data.productRecommendations
1974
+ }),
1975
+ meta: {
1976
+ sourceProductId: productId,
1977
+ recommendationCount: result.data.productRecommendations.length
1978
+ }
1979
+ });
1980
+ } catch (error) {
1981
+ this.logger.error("Error in getProductRecommendations", void 0, {
1982
+ error
1983
+ });
1984
+ const safeMessage = error instanceof Error ? error.message : "An unexpected error occurred while processing the request.";
1985
+ return formatResponse({
1986
+ success: false,
1987
+ message: "An error occurred while processing the request.",
1988
+ error: {
1989
+ message: safeMessage,
1990
+ details: error
1991
+ }
1992
+ });
1993
+ }
1994
+ }
1855
1995
  /**
1856
1996
  * Get multiple products by their handles using batch query
1857
1997
  */
1858
- async getProductsByHandles(handles, options) {
1998
+ async getProductsByHandles(params, options) {
1859
1999
  try {
2000
+ const { handles } = params;
1860
2001
  if (!handles || handles.length === 0) {
1861
2002
  return formatResponse({
1862
2003
  success: true,
@@ -3937,8 +4078,15 @@ var ShopifyCommerceClient = class extends BaseCommerceClient {
3937
4078
  /**
3938
4079
  * Get multiple products by their handles using batch query
3939
4080
  */
3940
- async getProductsByHandles(handles, options) {
3941
- return this.productService.getProductsByHandles(handles, options);
4081
+ async getProductsByHandles(params, options) {
4082
+ return this.productService.getProductsByHandles(params, options);
4083
+ }
4084
+ /**
4085
+ * Get product recommendations for a given product
4086
+ * Uses Shopify's productRecommendations API
4087
+ */
4088
+ async getProductRecommendations(params, options) {
4089
+ return this.productService.getProductRecommendations(params, options);
3942
4090
  }
3943
4091
  // ============================================================================
3944
4092
  // COLLECTION API METHODS - Now delegated to ProductService
@@ -3955,19 +4103,30 @@ var ShopifyCommerceClient = class extends BaseCommerceClient {
3955
4103
  async getCollection(params, options) {
3956
4104
  return this.productService.getCollection(params, options);
3957
4105
  }
3958
- /**
3959
- * Retrieve multiple collections by their handles with individual query parameters
3960
- * Each collection can have its own specific filtering, pagination, and sorting options
3961
- * @param params - Array of collection objects with handles and their respective query parameters
3962
- * @param options - Request options (headers, timeout, etc.)
3963
- * @returns Promise resolving to collections data with individual query results
3964
- */
3965
4106
  /**
3966
4107
  * Get multiple collections by their handles (preferred method name)
3967
4108
  */
3968
4109
  getCollectionsByHandles(params, options) {
3969
4110
  return this.productService.getCollectionsByHandles(params, options);
3970
4111
  }
4112
+ /**
4113
+ * Get collection filters (available filter options for a collection)
4114
+ */
4115
+ async getCollectionFilters(params, options) {
4116
+ const result = await this.productService.getCollection(
4117
+ { handle: params.handle },
4118
+ options
4119
+ );
4120
+ if (!result.success) {
4121
+ return result;
4122
+ }
4123
+ return formatResponse({
4124
+ success: true,
4125
+ message: "Collection filters retrieved successfully",
4126
+ data: result.meta?.filters || [],
4127
+ meta: void 0
4128
+ });
4129
+ }
3971
4130
  // ============================================================================
3972
4131
  // CART API METHODS - Delegated to CartService
3973
4132
  // ============================================================================
@@ -4069,7 +4228,8 @@ var ShopifyCommerceClient = class extends BaseCommerceClient {
4069
4228
  /**
4070
4229
  * Utility method to make GraphQL requests using Shopify client
4071
4230
  */
4072
- async graphqlRequest(query, variables) {
4231
+ async graphqlRequest(params) {
4232
+ const { query, variables } = params;
4073
4233
  this.logger.info("Making GraphQL request", {
4074
4234
  query: query.substring(0, 100) + "..."
4075
4235
  });
@@ -4240,7 +4400,7 @@ var PRODUCT_ENDPOINTS = {
4240
4400
  getCollections: (v = DEFAULT_VERSION) => `/api/${v}/collections`,
4241
4401
  getCollectionByHandle: (v = DEFAULT_VERSION, h) => `/api/${v}/collections/handle/${h}`,
4242
4402
  getCollectionById: (v = DEFAULT_VERSION, id) => `/api/${v}/collections/${id}`,
4243
- getCollectionsByHandels: (v = DEFAULT_VERSION) => `/api/${v}/collections/details`,
4403
+ getCollectionsByHandles: (v = DEFAULT_VERSION) => `/api/${v}/collections/details`,
4244
4404
  getCollectionFilters: (v = DEFAULT_VERSION, collectionHandle) => `/api/${v}/storefront/collections/${collectionHandle}/filters`
4245
4405
  };
4246
4406
 
@@ -4352,8 +4512,9 @@ var ProductService2 = class extends BaseCustomService {
4352
4512
  /**
4353
4513
  * Get multiple products by their handles using batch query
4354
4514
  */
4355
- async getProductsByHandles(handles, options) {
4515
+ async getProductsByHandles(params, options) {
4356
4516
  try {
4517
+ const { handles } = params;
4357
4518
  if (!handles || handles.length === 0) {
4358
4519
  return formatResponse({
4359
4520
  success: true,
@@ -4519,7 +4680,7 @@ var ProductService2 = class extends BaseCustomService {
4519
4680
  * Get multiple collections by their handles with individual query parameters
4520
4681
  * Each collection can have its own specific filtering, pagination, and sorting options
4521
4682
  */
4522
- async getCollectionsByHandels(params, options) {
4683
+ async getCollectionsByHandles(params, options) {
4523
4684
  try {
4524
4685
  const { handles } = params;
4525
4686
  if (!handles || handles.length === 0) {
@@ -4554,7 +4715,7 @@ var ProductService2 = class extends BaseCustomService {
4554
4715
  );
4555
4716
  }
4556
4717
  const result = await this.request(
4557
- PRODUCT_ENDPOINTS.getCollectionsByHandels(options?.version),
4718
+ PRODUCT_ENDPOINTS.getCollectionsByHandles(options?.version),
4558
4719
  "POST",
4559
4720
  payload,
4560
4721
  options
@@ -4567,7 +4728,9 @@ var ProductService2 = class extends BaseCustomService {
4567
4728
  meta: { pagination: void 0 }
4568
4729
  });
4569
4730
  }
4570
- const mappedCollections = result.collections.map((collection) => ({
4731
+ const mappedCollections = result.collections.filter(
4732
+ (collection) => collection !== null && collection !== void 0
4733
+ ).map((collection) => ({
4571
4734
  handle: collection.handle,
4572
4735
  data: mapGetCollectionsByHandelsResponse(collection),
4573
4736
  meta: {
@@ -4583,7 +4746,7 @@ var ProductService2 = class extends BaseCustomService {
4583
4746
  meta: void 0
4584
4747
  });
4585
4748
  } catch (error) {
4586
- this.logger.error("Error in getCollectionsByHandels", void 0, {
4749
+ this.logger.error("Error in getCollectionsByHandles", void 0, {
4587
4750
  error
4588
4751
  });
4589
4752
  const safeMessage = error instanceof Error ? error.message : "An unexpected error occurred while processing the request.";
@@ -5184,9 +5347,9 @@ var CustomBackendClient = class extends BaseCommerceClient {
5184
5347
  async getProducts(params, options) {
5185
5348
  return this.productService.getProducts(params, filterRestOptions(options));
5186
5349
  }
5187
- async getProductsByHandles(handles, options) {
5350
+ async getProductsByHandles(params, options) {
5188
5351
  return this.productService.getProductsByHandles(
5189
- handles,
5352
+ params,
5190
5353
  filterRestOptions(options)
5191
5354
  );
5192
5355
  }
@@ -5205,7 +5368,7 @@ var CustomBackendClient = class extends BaseCommerceClient {
5205
5368
  /**
5206
5369
  * Get a collection by ID
5207
5370
  */
5208
- getCollection(params, options) {
5371
+ async getCollection(params, options) {
5209
5372
  return this.productService.getCollection(
5210
5373
  params,
5211
5374
  filterRestOptions(options)
@@ -5218,8 +5381,8 @@ var CustomBackendClient = class extends BaseCommerceClient {
5218
5381
  * @param options - Request options (headers, timeout, etc.)
5219
5382
  * @returns Promise resolving to collections data with individual query results
5220
5383
  */
5221
- getCollectionsByHandels(params, options) {
5222
- return this.productService.getCollectionsByHandels(
5384
+ async getCollectionsByHandles(params, options) {
5385
+ return this.productService.getCollectionsByHandles(
5223
5386
  params,
5224
5387
  filterRestOptions(options)
5225
5388
  );
@@ -5256,12 +5419,6 @@ var CustomBackendClient = class extends BaseCommerceClient {
5256
5419
  async createCheckout(params, options) {
5257
5420
  return this.cartService.createCheckout(params, filterRestOptions(options));
5258
5421
  }
5259
- async updateCheckout(id, data, options) {
5260
- throw new Error("Checkout service not implemented in custom adapter");
5261
- }
5262
- async completeCheckout(id, paymentData, options) {
5263
- throw new Error("Checkout service not implemented in custom adapter");
5264
- }
5265
5422
  // ========================================
5266
5423
  // CUSTOMER OPERATIONS
5267
5424
  // ========================================