@shopkit/data-layer 1.6.0 → 1.8.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 +31 -0
- package/dist/adapters/index.d.mts +2 -2
- package/dist/adapters/index.d.ts +2 -2
- package/dist/adapters/index.js +280 -2
- package/dist/adapters/index.js.map +1 -1
- package/dist/adapters/index.mjs +280 -2
- package/dist/adapters/index.mjs.map +1 -1
- package/dist/index.d.mts +23 -4
- package/dist/index.d.ts +23 -4
- package/dist/index.js +306 -2
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +305 -3
- package/dist/index.mjs.map +1 -1
- package/dist/{interface-BGV7d5F8.d.ts → interface-CWuOTUIW.d.ts} +8 -1
- package/dist/{interface-CgPiwpPe.d.mts → interface-D4gQCRsx.d.mts} +8 -1
- package/dist/models/index.d.mts +174 -5
- package/dist/models/index.d.ts +174 -5
- package/dist/{service-Cb074q9F.d.ts → service-BEiNHL9V.d.mts} +11 -2
- package/dist/{service-BPzeuSLS.d.mts → service-C4eDXKmf.d.ts} +11 -2
- package/dist/static-params/index.d.mts +1 -1
- package/dist/static-params/index.d.ts +1 -1
- package/dist/static-params/index.js +7 -0
- package/dist/static-params/index.js.map +1 -1
- package/dist/static-params/index.mjs +7 -0
- package/dist/static-params/index.mjs.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -5,6 +5,7 @@ A comprehensive, production-ready data layer package for e-commerce applications
|
|
|
5
5
|
## Table of Contents
|
|
6
6
|
|
|
7
7
|
- [Features](#features)
|
|
8
|
+
- [API Gateway Rate Limits](#api-gateway-rate-limits-shopper-ip)
|
|
8
9
|
- [Installation](#installation)
|
|
9
10
|
- [Quick Start](#quick-start)
|
|
10
11
|
- [Configuration](#configuration)
|
|
@@ -80,6 +81,36 @@ export const generateStaticParams = createCollectionProductStaticParams(
|
|
|
80
81
|
);
|
|
81
82
|
```
|
|
82
83
|
|
|
84
|
+
**Skipping build-time prerendering.** Set `SKIP_BUILD_STATIC_PARAMS=true` at build time and every
|
|
85
|
+
factory returns `[]` without calling the API; pages render on their first request instead
|
|
86
|
+
(`dynamicParams`). Use it when the API gateway rate-limits the build host: a 429 fails a page render
|
|
87
|
+
(so ISR keeps the last good page), which would otherwise fail a large build.
|
|
88
|
+
|
|
89
|
+
## API Gateway Rate Limits (shopper IP)
|
|
90
|
+
|
|
91
|
+
The OS API gateway rate-limits per shopper IP and per merchant (`gk-merchant-id`, which the custom
|
|
92
|
+
adapter already sends). A call a storefront server makes **for a shopper** must say who the shopper is,
|
|
93
|
+
or every shopper looks like one client:
|
|
94
|
+
|
|
95
|
+
```typescript
|
|
96
|
+
import { shopperForwardHeaders } from "@shopkit/data-layer";
|
|
97
|
+
|
|
98
|
+
// In an uncached route handler, e.g. a search proxy:
|
|
99
|
+
const res = await fetch(url, {
|
|
100
|
+
cache: "no-store",
|
|
101
|
+
headers: { "gk-merchant-id": merchantId, ...shopperForwardHeaders(request) },
|
|
102
|
+
});
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
- `getShopperIp(headers, { trustedHops })` reads the **right-most** `x-forwarded-for` entry — the one our
|
|
106
|
+
load balancer appends (`trustedHops`, default 1). Entries to its left and `cf-connecting-ip` /
|
|
107
|
+
`true-client-ip` / `x-real-ip` come from the shopper and are ignored. A client port is stripped.
|
|
108
|
+
- `shopperForwardHeaders(request)` returns `{ "x-forwarded-for": ip }`, or `{}` when no IP resolves.
|
|
109
|
+
- **Uncached fetches only.** Next.js keys its fetch cache on request headers, so a per-shopper header on a
|
|
110
|
+
cached fetch (`next: { revalidate, tags }`) stores one entry per IP. ISR renders send no shopper IP.
|
|
111
|
+
- A gateway 429 counts as "backend unavailable", like a 5xx: `getProduct` / `getCollection` return
|
|
112
|
+
`success: false` rather than "not found", so a page can keep its last good copy.
|
|
113
|
+
|
|
83
114
|
## Installation
|
|
84
115
|
|
|
85
116
|
```bash
|
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import { I as IShopifyConfig, S as ShopifyCommerceClient, a as ICustomConfig, C as CustomBackendClient } from '../service-
|
|
1
|
+
import { I as IShopifyConfig, S as ShopifyCommerceClient, a as ICustomConfig, C as CustomBackendClient } from '../service-BEiNHL9V.mjs';
|
|
2
2
|
import '../models/index.mjs';
|
|
3
|
-
import '../interface-
|
|
3
|
+
import '../interface-D4gQCRsx.mjs';
|
|
4
4
|
|
|
5
5
|
/**
|
|
6
6
|
* Shopify adapter for the commerce library
|
package/dist/adapters/index.d.ts
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
|
-
import { I as IShopifyConfig, S as ShopifyCommerceClient, a as ICustomConfig, C as CustomBackendClient } from '../service-
|
|
1
|
+
import { I as IShopifyConfig, S as ShopifyCommerceClient, a as ICustomConfig, C as CustomBackendClient } from '../service-C4eDXKmf.js';
|
|
2
2
|
import '../models/index.js';
|
|
3
|
-
import '../interface-
|
|
3
|
+
import '../interface-CWuOTUIW.js';
|
|
4
4
|
|
|
5
5
|
/**
|
|
6
6
|
* Shopify adapter for the commerce library
|
package/dist/adapters/index.js
CHANGED
|
@@ -162,7 +162,7 @@ function createDomainLogger(domain, adapter, config = {}) {
|
|
|
162
162
|
function isUpstreamUnavailable(error) {
|
|
163
163
|
const status = error?.status;
|
|
164
164
|
if (typeof status !== "number") return true;
|
|
165
|
-
return status >= 500;
|
|
165
|
+
return status >= 500 || status === 429;
|
|
166
166
|
}
|
|
167
167
|
function formatResponse(params) {
|
|
168
168
|
const { success, message, data = null, error = null, meta = {} } = params;
|
|
@@ -308,6 +308,16 @@ var BaseCommerceClient = class {
|
|
|
308
308
|
queryCollections(params, options) {
|
|
309
309
|
this.throwNotImplemented("queryCollections");
|
|
310
310
|
}
|
|
311
|
+
/**
|
|
312
|
+
* Read a page of a collection's products, with one card per matching variant
|
|
313
|
+
* @param params - Handle plus page/per_page, sort, filter, fields
|
|
314
|
+
* @param options - Request options (headers, timeout, etc.)
|
|
315
|
+
* @returns Promise resolving to a VariantCardsPageDto
|
|
316
|
+
* @throws NotImplementedError if not implemented in adapter (custom backend only)
|
|
317
|
+
*/
|
|
318
|
+
getCollectionVariantCards(params, options) {
|
|
319
|
+
this.throwNotImplemented("getCollectionVariantCards");
|
|
320
|
+
}
|
|
311
321
|
// ========================================
|
|
312
322
|
// ORDER OPERATIONS
|
|
313
323
|
// ========================================
|
|
@@ -3807,7 +3817,8 @@ var PRODUCT_ENDPOINTS = {
|
|
|
3807
3817
|
getCollectionById: (v = DEFAULT_VERSION, id) => `/api/${v}/collections/${encodeURIComponent(id)}`,
|
|
3808
3818
|
getCollectionsByHandles: (v = DEFAULT_VERSION) => `/api/${v}/collections/details`,
|
|
3809
3819
|
getCollectionFilters: (v = DEFAULT_VERSION, collectionHandle) => `/api/${v}/storefront/collections/${encodeURIComponent(collectionHandle)}/filters`,
|
|
3810
|
-
queryCollections: (v = DEFAULT_VERSION) => `/api/${v}/collections/query
|
|
3820
|
+
queryCollections: (v = DEFAULT_VERSION) => `/api/${v}/collections/query`,
|
|
3821
|
+
collectionVariants: (v = DEFAULT_VERSION, handle) => `/api/${v}/collections/${encodeURIComponent(handle)}/variants`
|
|
3811
3822
|
};
|
|
3812
3823
|
|
|
3813
3824
|
// src/adapters/custom/product/service.ts
|
|
@@ -4472,7 +4483,268 @@ var ProductService2 = class extends BaseCustomService {
|
|
|
4472
4483
|
});
|
|
4473
4484
|
}
|
|
4474
4485
|
}
|
|
4486
|
+
/**
|
|
4487
|
+
* A page of a collection's products, with one card per matching variant
|
|
4488
|
+
* (POST /api/v1/collections/{handle}/variants). A POST because filters are
|
|
4489
|
+
* nested; it is still a read and answers 200.
|
|
4490
|
+
*
|
|
4491
|
+
* With `allVariants: true`, follows `next_cursor` (same body + `after`,
|
|
4492
|
+
* 100 cards per call) and returns the whole page's variants in one result.
|
|
4493
|
+
* The result is complete or it is a failure — never a partial page, which
|
|
4494
|
+
* would be cached as if it were complete. It fails (`UPSTREAM_UNAVAILABLE`)
|
|
4495
|
+
* when a follow-up call fails, when the cursor repeats, or when the page is
|
|
4496
|
+
* not done within ALL_VARIANTS_MAX_CALLS calls or ALL_VARIANTS_DEADLINE_MS.
|
|
4497
|
+
*/
|
|
4498
|
+
async getCollectionVariantCards(params, options) {
|
|
4499
|
+
const handle = typeof params?.handle === "string" ? params.handle.trim() : "";
|
|
4500
|
+
if (!handle) {
|
|
4501
|
+
return formatResponse({
|
|
4502
|
+
success: false,
|
|
4503
|
+
message: "Missing required variable: 'handle'",
|
|
4504
|
+
error: {
|
|
4505
|
+
code: "QUERY_REJECTED",
|
|
4506
|
+
message: "handle: is required"
|
|
4507
|
+
}
|
|
4508
|
+
});
|
|
4509
|
+
}
|
|
4510
|
+
if (handle.includes("/") || handle === "." || handle === "..") {
|
|
4511
|
+
return formatResponse({
|
|
4512
|
+
success: false,
|
|
4513
|
+
message: "Collection not found.",
|
|
4514
|
+
error: {
|
|
4515
|
+
code: "NOT_FOUND",
|
|
4516
|
+
message: `No collection with handle ${handle}`
|
|
4517
|
+
}
|
|
4518
|
+
});
|
|
4519
|
+
}
|
|
4520
|
+
const payload = buildCollectionVariantsPayload(params);
|
|
4521
|
+
const requestOptions = {
|
|
4522
|
+
...options || {},
|
|
4523
|
+
// Same coverage as queryCollections: the broad tag for catalog-wide
|
|
4524
|
+
// purges plus the collection's own, which product.updated /
|
|
4525
|
+
// collection.updated webhooks already purge. No `revalidate`.
|
|
4526
|
+
next: {
|
|
4527
|
+
...options?.next || {},
|
|
4528
|
+
tags: [
|
|
4529
|
+
cacheTags.CacheTags.collections(),
|
|
4530
|
+
cacheTags.CacheTags.collection(handle),
|
|
4531
|
+
...options?.next?.tags || []
|
|
4532
|
+
]
|
|
4533
|
+
}
|
|
4534
|
+
};
|
|
4535
|
+
const endpoint = PRODUCT_ENDPOINTS.collectionVariants(
|
|
4536
|
+
options?.version,
|
|
4537
|
+
handle
|
|
4538
|
+
);
|
|
4539
|
+
const allVariants = params.allVariants === true;
|
|
4540
|
+
const deadline = allVariants ? AbortSignal.timeout(ALL_VARIANTS_DEADLINE_MS) : void 0;
|
|
4541
|
+
const callOptions = () => deadline ? {
|
|
4542
|
+
...requestOptions,
|
|
4543
|
+
signal: anySignal([
|
|
4544
|
+
deadline,
|
|
4545
|
+
options?.signal ?? AbortSignal.timeout(options?.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS)
|
|
4546
|
+
])
|
|
4547
|
+
} : requestOptions;
|
|
4548
|
+
let followUp = false;
|
|
4549
|
+
try {
|
|
4550
|
+
let result = await this.request(endpoint, "POST", payload, callOptions());
|
|
4551
|
+
if (!result?.data) return noVariantCardsData(result?.request_id);
|
|
4552
|
+
const page = {
|
|
4553
|
+
...result.data,
|
|
4554
|
+
variants: Array.isArray(result.data.variants) ? result.data.variants : []
|
|
4555
|
+
};
|
|
4556
|
+
const errors = Array.isArray(result.errors) ? [...result.errors] : [];
|
|
4557
|
+
if (allVariants) {
|
|
4558
|
+
followUp = true;
|
|
4559
|
+
const variants = [];
|
|
4560
|
+
const seenIds = /* @__PURE__ */ new Set();
|
|
4561
|
+
const addCards = (cards) => {
|
|
4562
|
+
for (const card of Array.isArray(cards) ? cards : []) {
|
|
4563
|
+
if (typeof card?.id === "string") {
|
|
4564
|
+
if (seenIds.has(card.id)) continue;
|
|
4565
|
+
seenIds.add(card.id);
|
|
4566
|
+
}
|
|
4567
|
+
variants.push(card);
|
|
4568
|
+
}
|
|
4569
|
+
};
|
|
4570
|
+
addCards(page.variants);
|
|
4571
|
+
const seenCursors = new Set(
|
|
4572
|
+
typeof payload.after === "string" ? [payload.after] : []
|
|
4573
|
+
);
|
|
4574
|
+
let cursor = page.next_cursor;
|
|
4575
|
+
let calls = 1;
|
|
4576
|
+
while (cursor) {
|
|
4577
|
+
if (seenCursors.has(cursor)) {
|
|
4578
|
+
return incompleteVariantCards(
|
|
4579
|
+
"the backend returned a cursor it had already sent",
|
|
4580
|
+
result.request_id,
|
|
4581
|
+
this.logger
|
|
4582
|
+
);
|
|
4583
|
+
}
|
|
4584
|
+
if (calls >= ALL_VARIANTS_MAX_CALLS) {
|
|
4585
|
+
return incompleteVariantCards(
|
|
4586
|
+
`the page has more cards than ${ALL_VARIANTS_MAX_CALLS} calls of ${MAX_VARIANT_CARDS_PER_CALL} hold`,
|
|
4587
|
+
result.request_id,
|
|
4588
|
+
this.logger
|
|
4589
|
+
);
|
|
4590
|
+
}
|
|
4591
|
+
seenCursors.add(cursor);
|
|
4592
|
+
result = await this.request(
|
|
4593
|
+
endpoint,
|
|
4594
|
+
"POST",
|
|
4595
|
+
{ ...payload, after: cursor },
|
|
4596
|
+
callOptions()
|
|
4597
|
+
);
|
|
4598
|
+
calls++;
|
|
4599
|
+
if (!result?.data) return noVariantCardsData(result?.request_id);
|
|
4600
|
+
addCards(result.data.variants);
|
|
4601
|
+
if (Array.isArray(result.errors)) errors.push(...result.errors);
|
|
4602
|
+
cursor = result.data.next_cursor;
|
|
4603
|
+
}
|
|
4604
|
+
page.variants = variants;
|
|
4605
|
+
page.next_cursor = null;
|
|
4606
|
+
}
|
|
4607
|
+
const distinctErrors = dedupeErrors(errors);
|
|
4608
|
+
return formatResponse({
|
|
4609
|
+
success: true,
|
|
4610
|
+
message: "Collection variants retrieved successfully.",
|
|
4611
|
+
data: page,
|
|
4612
|
+
meta: {
|
|
4613
|
+
requestId: result.request_id,
|
|
4614
|
+
...distinctErrors.length > 0 ? { errors: distinctErrors } : {}
|
|
4615
|
+
}
|
|
4616
|
+
});
|
|
4617
|
+
} catch (error) {
|
|
4618
|
+
this.logger.error("Error in getCollectionVariantCards", void 0, {
|
|
4619
|
+
error
|
|
4620
|
+
});
|
|
4621
|
+
const body = error?.body;
|
|
4622
|
+
if (deadline?.aborted) {
|
|
4623
|
+
return incompleteVariantCards(
|
|
4624
|
+
`the page was not complete within ${ALL_VARIANTS_DEADLINE_MS / 1e3}s`,
|
|
4625
|
+
body?.request_id,
|
|
4626
|
+
this.logger
|
|
4627
|
+
);
|
|
4628
|
+
}
|
|
4629
|
+
if (isUpstreamUnavailable(error)) {
|
|
4630
|
+
return formatResponse({
|
|
4631
|
+
success: false,
|
|
4632
|
+
message: "An error occurred while processing the request.",
|
|
4633
|
+
error: {
|
|
4634
|
+
code: "UPSTREAM_UNAVAILABLE",
|
|
4635
|
+
message: typeof error?.status === "number" ? `Request failed: ${error.status}` : "Collection variants request did not complete."
|
|
4636
|
+
},
|
|
4637
|
+
meta: { requestId: body?.request_id }
|
|
4638
|
+
});
|
|
4639
|
+
}
|
|
4640
|
+
const upstreamErrors = Array.isArray(body?.errors) ? body.errors : [];
|
|
4641
|
+
if (error?.status === 404) {
|
|
4642
|
+
if (!followUp && upstreamErrors[0]?.code === "NOT_FOUND") {
|
|
4643
|
+
return formatResponse({
|
|
4644
|
+
success: false,
|
|
4645
|
+
message: "Collection not found.",
|
|
4646
|
+
error: {
|
|
4647
|
+
code: "NOT_FOUND",
|
|
4648
|
+
message: upstreamErrors[0]?.message || `No collection with handle ${handle}`
|
|
4649
|
+
},
|
|
4650
|
+
meta: { requestId: body?.request_id }
|
|
4651
|
+
});
|
|
4652
|
+
}
|
|
4653
|
+
return formatResponse({
|
|
4654
|
+
success: false,
|
|
4655
|
+
message: "An error occurred while processing the request.",
|
|
4656
|
+
error: {
|
|
4657
|
+
code: "UPSTREAM_UNAVAILABLE",
|
|
4658
|
+
message: "Request failed: 404"
|
|
4659
|
+
},
|
|
4660
|
+
meta: { requestId: body?.request_id }
|
|
4661
|
+
});
|
|
4662
|
+
}
|
|
4663
|
+
return formatResponse({
|
|
4664
|
+
success: false,
|
|
4665
|
+
message: "The collection variants request was rejected.",
|
|
4666
|
+
error: {
|
|
4667
|
+
code: "QUERY_REJECTED",
|
|
4668
|
+
message: upstreamErrors[0]?.message || error.message,
|
|
4669
|
+
details: upstreamErrors
|
|
4670
|
+
},
|
|
4671
|
+
meta: { requestId: body?.request_id }
|
|
4672
|
+
});
|
|
4673
|
+
}
|
|
4674
|
+
}
|
|
4475
4675
|
};
|
|
4676
|
+
function incompleteVariantCards(reason, requestId, logger2) {
|
|
4677
|
+
logger2.warn(`getCollectionVariantCards allVariants incomplete: ${reason}`);
|
|
4678
|
+
return formatResponse({
|
|
4679
|
+
success: false,
|
|
4680
|
+
message: "Collection variants page is incomplete.",
|
|
4681
|
+
error: {
|
|
4682
|
+
code: "UPSTREAM_UNAVAILABLE",
|
|
4683
|
+
message: `allVariants: ${reason}; not returning a partial page.`
|
|
4684
|
+
},
|
|
4685
|
+
meta: { requestId }
|
|
4686
|
+
});
|
|
4687
|
+
}
|
|
4688
|
+
function dedupeErrors(errors) {
|
|
4689
|
+
const seen = /* @__PURE__ */ new Set();
|
|
4690
|
+
return errors.filter((e) => {
|
|
4691
|
+
const err = e;
|
|
4692
|
+
const key = JSON.stringify([err?.code, err?.message]);
|
|
4693
|
+
if (seen.has(key)) return false;
|
|
4694
|
+
seen.add(key);
|
|
4695
|
+
return true;
|
|
4696
|
+
});
|
|
4697
|
+
}
|
|
4698
|
+
function anySignal(signals) {
|
|
4699
|
+
const controller = new AbortController();
|
|
4700
|
+
for (const signal of signals) {
|
|
4701
|
+
if (signal.aborted) {
|
|
4702
|
+
controller.abort(signal.reason);
|
|
4703
|
+
break;
|
|
4704
|
+
}
|
|
4705
|
+
signal.addEventListener("abort", () => controller.abort(signal.reason), {
|
|
4706
|
+
once: true
|
|
4707
|
+
});
|
|
4708
|
+
}
|
|
4709
|
+
return controller.signal;
|
|
4710
|
+
}
|
|
4711
|
+
function noVariantCardsData(requestId) {
|
|
4712
|
+
return formatResponse({
|
|
4713
|
+
success: false,
|
|
4714
|
+
message: "Collection variants request returned no data.",
|
|
4715
|
+
error: {
|
|
4716
|
+
code: "UPSTREAM_UNAVAILABLE",
|
|
4717
|
+
message: "No data in collection variants response."
|
|
4718
|
+
},
|
|
4719
|
+
meta: { requestId }
|
|
4720
|
+
});
|
|
4721
|
+
}
|
|
4722
|
+
var COLLECTION_VARIANTS_KEYS = [
|
|
4723
|
+
"filter",
|
|
4724
|
+
"fields",
|
|
4725
|
+
"product",
|
|
4726
|
+
"sort",
|
|
4727
|
+
"page",
|
|
4728
|
+
"per_page",
|
|
4729
|
+
"limit",
|
|
4730
|
+
"after",
|
|
4731
|
+
"ratings",
|
|
4732
|
+
"metafields"
|
|
4733
|
+
];
|
|
4734
|
+
var MAX_VARIANT_CARDS_PER_CALL = 100;
|
|
4735
|
+
var ALL_VARIANTS_MAX_CALLS = 20;
|
|
4736
|
+
var ALL_VARIANTS_DEADLINE_MS = 15e3;
|
|
4737
|
+
function buildCollectionVariantsPayload(params) {
|
|
4738
|
+
const source = params || {};
|
|
4739
|
+
const payload = {};
|
|
4740
|
+
for (const key of COLLECTION_VARIANTS_KEYS) {
|
|
4741
|
+
if (source[key] !== void 0) payload[key] = source[key];
|
|
4742
|
+
}
|
|
4743
|
+
if (source.allVariants === true) {
|
|
4744
|
+
payload.limit = MAX_VARIANT_CARDS_PER_CALL;
|
|
4745
|
+
}
|
|
4746
|
+
return payload;
|
|
4747
|
+
}
|
|
4476
4748
|
var COLLECTIONS_QUERY_KEYS = [
|
|
4477
4749
|
"filter",
|
|
4478
4750
|
"fields",
|
|
@@ -5114,6 +5386,12 @@ var CustomBackendClient = class extends BaseCommerceClient {
|
|
|
5114
5386
|
filterRestOptions(options)
|
|
5115
5387
|
);
|
|
5116
5388
|
}
|
|
5389
|
+
async getCollectionVariantCards(params, options) {
|
|
5390
|
+
return this.productService.getCollectionVariantCards(
|
|
5391
|
+
params,
|
|
5392
|
+
filterRestOptions(options)
|
|
5393
|
+
);
|
|
5394
|
+
}
|
|
5117
5395
|
// ========================================
|
|
5118
5396
|
// CART OPERATIONS
|
|
5119
5397
|
// ========================================
|