@contentstack/studio-client 3.2.0 → 4.0.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.
Files changed (95) hide show
  1. package/dist/breakpoints/BreakpointManager.js +7 -5
  2. package/dist/breakpoints/BreakpointManager.js.map +1 -1
  3. package/dist/breakpoints/breakpoint.js +3 -2
  4. package/dist/breakpoints/breakpoint.js.map +1 -1
  5. package/dist/canvas/canvas.utils.js +13 -1
  6. package/dist/canvas/canvas.utils.js.map +1 -1
  7. package/dist/composable-studio/build-scoped-data.js +12 -35
  8. package/dist/composable-studio/build-scoped-data.js.map +1 -1
  9. package/dist/composable-studio/sdk.js +1064 -430
  10. package/dist/composable-studio/sdk.js.map +1 -1
  11. package/dist/composable-studio/studio-intelligence.manager.js +5 -2
  12. package/dist/composable-studio/studio-intelligence.manager.js.map +1 -1
  13. package/dist/config/config.schema.js +45 -8
  14. package/dist/config/config.schema.js.map +1 -1
  15. package/dist/config/default-config.js +10 -3
  16. package/dist/config/default-config.js.map +1 -1
  17. package/dist/config/process-user-config.js +37 -1
  18. package/dist/config/process-user-config.js.map +1 -1
  19. package/dist/config/stack-sdk-wrapper.js +36 -1
  20. package/dist/config/stack-sdk-wrapper.js.map +1 -1
  21. package/dist/context-menu/context-menu.js +5 -2
  22. package/dist/context-menu/context-menu.js.map +1 -1
  23. package/dist/design/handle-active-style-change.js +3 -2
  24. package/dist/design/handle-active-style-change.js.map +1 -1
  25. package/dist/dnd/dnd-event.js +2 -1
  26. package/dist/dnd/dnd-event.js.map +1 -1
  27. package/dist/dnd/dnd-manager.js +3 -1
  28. package/dist/dnd/dnd-manager.js.map +1 -1
  29. package/dist/editor.d.ts +250 -0
  30. package/dist/editor.js +11 -0
  31. package/dist/editor.js.map +1 -0
  32. package/dist/get-active-node-screenshot/get-node-screenshot-event.js +2 -1
  33. package/dist/get-active-node-screenshot/get-node-screenshot-event.js.map +1 -1
  34. package/dist/hidden-element-notification/hidden-element-notification-event.js +2 -1
  35. package/dist/hidden-element-notification/hidden-element-notification-event.js.map +1 -1
  36. package/dist/highlight-node/highlight-node-manager.js +225 -15
  37. package/dist/highlight-node/highlight-node-manager.js.map +1 -1
  38. package/dist/highlight-node/highlight-node.js +42 -6
  39. package/dist/highlight-node/highlight-node.js.map +1 -1
  40. package/dist/highlight-spacing/highlight-spacing-events.js +2 -1
  41. package/dist/highlight-spacing/highlight-spacing-events.js.map +1 -1
  42. package/dist/index.d.ts +1006 -436
  43. package/dist/index.js +12 -13
  44. package/dist/index.js.map +1 -1
  45. package/dist/url-change/url-change.js +4 -3
  46. package/dist/url-change/url-change.js.map +1 -1
  47. package/dist/url-metadata/build-template-query.js +14 -3
  48. package/dist/url-metadata/build-template-query.js.map +1 -1
  49. package/dist/utils/canvas.js +2 -1
  50. package/dist/utils/canvas.js.map +1 -1
  51. package/dist/utils/check-bindings.js +233 -0
  52. package/dist/utils/check-bindings.js.map +1 -0
  53. package/dist/utils/classify-response-error.js +288 -0
  54. package/dist/utils/classify-response-error.js.map +1 -0
  55. package/dist/utils/composable-studio-error.js +36 -20
  56. package/dist/utils/composable-studio-error.js.map +1 -1
  57. package/dist/utils/composition-not-found.js +52 -0
  58. package/dist/utils/composition-not-found.js.map +1 -0
  59. package/dist/utils/constants.js +21 -2
  60. package/dist/utils/constants.js.map +1 -1
  61. package/dist/utils/degraded-finding.js +166 -0
  62. package/dist/utils/degraded-finding.js.map +1 -0
  63. package/dist/utils/editor-mode.js +1 -1
  64. package/dist/utils/http-error.constants.js +12 -46
  65. package/dist/utils/http-error.constants.js.map +1 -1
  66. package/dist/utils/include-path-rules.js +40 -1
  67. package/dist/utils/include-path-rules.js.map +1 -1
  68. package/dist/utils/is-composition-being-edited.js +1 -1
  69. package/dist/utils/is-inside-iframe.js +1 -1
  70. package/dist/utils/is-inside-visual-builder-frame.js +1 -1
  71. package/dist/utils/parse-ui.js +60 -0
  72. package/dist/utils/parse-ui.js.map +1 -0
  73. package/dist/utils/query-param.js +1 -1
  74. package/dist/utils/query-param.js.map +1 -1
  75. package/dist/utils/reference-stub.js +75 -0
  76. package/dist/utils/reference-stub.js.map +1 -0
  77. package/dist/utils/reference_fetcher.js +44 -3
  78. package/dist/utils/reference_fetcher.js.map +1 -1
  79. package/dist/utils/require-stack.js +141 -0
  80. package/dist/utils/require-stack.js.map +1 -0
  81. package/dist/utils/served-by.js +33 -0
  82. package/dist/utils/served-by.js.map +1 -0
  83. package/dist/utils/studio-error-codes.js +253 -0
  84. package/dist/utils/studio-error-codes.js.map +1 -0
  85. package/dist/utils/studio-error.js +122 -0
  86. package/dist/utils/studio-error.js.map +1 -0
  87. package/dist/utils/studio-messaging.js +25 -0
  88. package/dist/utils/studio-messaging.js.map +1 -0
  89. package/dist/visual-builder/composition-save-event.js +2 -1
  90. package/dist/visual-builder/composition-save-event.js.map +1 -1
  91. package/package.json +19 -6
  92. package/dist/utils/error-messages.default.js +0 -141
  93. package/dist/utils/error-messages.default.js.map +0 -1
  94. package/dist/utils/error-messages.js +0 -47
  95. package/dist/utils/error-messages.js.map +0 -1
@@ -0,0 +1,288 @@
1
+ import { DEFAULT_COMPOSITION_TYPE_UID } from '../config/config.constant.js';
2
+ import { getStatusCode, HttpStatus, ContentstackErrorCode, isNetworkError } from './http-error.constants.js';
3
+ import { buildStudioErrorContext, createStudioError } from './studio-error.js';
4
+ import { StudioErrorCode } from './studio-error-codes.js';
5
+
6
+ /**
7
+ * Turns a delivery-API failure into a diagnosis, for the cases that have one.
8
+ *
9
+ * Returns `undefined` when nothing here recognises the response, and the
10
+ * caller's existing handling takes over. That is what makes this safe to grow
11
+ * one code at a time: a case is either diagnosed or left exactly as it was.
12
+ *
13
+ * What arrives here is the delivery SDK's `APIError`, which keeps `status`,
14
+ * `error_code` and `error_message` and discards the response's `errors` object.
15
+ * Conditions are written against the three fields that survive.
16
+ */
17
+ /**
18
+ * Whether the uid was chosen decides which cause leads. A developer who set
19
+ * nothing cannot have made a typo, and one who set a value is not going to find
20
+ * the default in their code.
21
+ *
22
+ * Both lists rank rather than assert, so both are written as possibilities with
23
+ * a check attached. We have proved the content type is not on the stack — that
24
+ * is the headline. Why it is not on the stack is a guess between two, and copy
25
+ * that states a guess as fact sends someone to correct a value that was right.
26
+ */
27
+ function contentTypeCauses(config) {
28
+ const notInstalled = {
29
+ cause: "This stack may not have Studio's content types installed.",
30
+ fix: "Check the API key points at the stack you meant. If it does, install Studio's content types there.",
31
+ };
32
+ if (config.contentTypeUidWasSupplied) {
33
+ return [
34
+ {
35
+ cause: `The uid "${config.contentTypeUid}" may be misspelled.`,
36
+ fix: "Compare it with the content type in Contentstack.",
37
+ },
38
+ notInstalled,
39
+ ];
40
+ }
41
+ return [
42
+ {
43
+ cause: `contentTypeUid was not set, so the default "${DEFAULT_COMPOSITION_TYPE_UID}" was used. This stack may use a different uid.`,
44
+ fix: "Find the compositions content type in Contentstack and set contentTypeUid to its uid.",
45
+ },
46
+ notInstalled,
47
+ ];
48
+ }
49
+ /**
50
+ * 141 carries four meanings and `error_message` is the only separator. Matched
51
+ * on the leading phrase so the trailing "Please try again." can change freely.
52
+ * Verified against a live stack, not taken from a document.
53
+ */
54
+ const ENVIRONMENT_NOT_FOUND_MESSAGE = /^\s*environment was not found/i;
55
+ const LANGUAGE_NOT_FOUND_MESSAGE = /^\s*language was not found/i;
56
+ /**
57
+ * Byte-identical responses, so this ranks and never asserts — one says change a
58
+ * value, the other change the host, and picking wrong edits what was right.
59
+ */
60
+ function stackNotFoundCauses(host) {
61
+ return [
62
+ {
63
+ cause: "The API key may be wrong.",
64
+ fix: "Compare it with the stack's API credentials in Contentstack.",
65
+ },
66
+ {
67
+ cause: `The API key may be right and ${host ?? "the host"} may be the wrong region for it. A key only answers on the region its stack lives in.`,
68
+ fix: "Check which region the stack is in, and set the host to match. The fix is the host, not the key.",
69
+ },
70
+ ];
71
+ }
72
+ /**
73
+ * A token that does not cover the environment answers here, not as a token
74
+ * error — so without scope we call an environment missing while it sits on the
75
+ * stack in front of the reader.
76
+ */
77
+ /**
78
+ * The environment is named from our own request, since the API names nothing.
79
+ * It can be absent on the legacy JS stack, where empty quotes would read as a
80
+ * bug in us, so the copy drops to a wording that claims no name.
81
+ */
82
+ function environmentNotFound(context, status, errorCode) {
83
+ const environment = context.environment;
84
+ const named = environment
85
+ ? `"${environment}"`
86
+ : "the environment it was sent";
87
+ return createStudioError({
88
+ code: StudioErrorCode.ENVIRONMENT_NOT_FOUND,
89
+ headline: environment
90
+ ? `Contentstack did not find the environment "${environment}".`
91
+ : "Contentstack did not find the environment this request was sent to.",
92
+ causes: [
93
+ {
94
+ cause: `The environment ${named} may not exist on this stack, or may have been renamed.`,
95
+ fix: "Compare the name with the environments in Contentstack.",
96
+ },
97
+ {
98
+ cause: "The environment may exist but sit outside the delivery token's scope. A delivery token is scoped to specific environments.",
99
+ fix: `Check that the delivery token in use covers ${named}.`,
100
+ },
101
+ ],
102
+ context,
103
+ findings: { environment, status, errorCode },
104
+ });
105
+ }
106
+ /** Casing leads: it is the one difference a reader cannot see by looking. */
107
+ function localeCauses(locale) {
108
+ return [
109
+ {
110
+ cause: `The code may not match the one on the stack — "${locale}" and "${locale.toLowerCase()}" are different values.`,
111
+ fix: "Compare it with the languages in Contentstack, exactly as they are written there.",
112
+ },
113
+ {
114
+ cause: "The language may never have been added to this stack.",
115
+ fix: "Add it in Contentstack, or ask for one the stack has.",
116
+ },
117
+ ];
118
+ }
119
+ /** The address asked for a language the stack does not have: a missing page. */
120
+ function urlLocaleNotFound(locale, requestedUrl, context, status, errorCode) {
121
+ return createStudioError({
122
+ code: StudioErrorCode.URL_LOCALE_NOT_FOUND,
123
+ headline: `${requestedUrl ? `"${requestedUrl}"` : "This address"} asks for the language "${locale}", which is not set up on this stack.`,
124
+ causes: [
125
+ {
126
+ cause: `The address may be wrong — "${locale}" is not one of this stack's languages.`,
127
+ fix: "Check the language segment against the languages in Contentstack.",
128
+ },
129
+ {
130
+ cause: "The language may have been removed from the stack after this address was published.",
131
+ fix: "Add it back, or redirect the address to a language the stack has.",
132
+ },
133
+ ],
134
+ context,
135
+ // What a host reads to decide what to render in the page's place.
136
+ findings: {
137
+ requestedUrl,
138
+ locale,
139
+ localeSource: "url-pattern",
140
+ status,
141
+ errorCode,
142
+ },
143
+ });
144
+ }
145
+ /** The SDK was configured with a language the stack does not have. */
146
+ function localeNotConfigured(locale, context, status, errorCode) {
147
+ return createStudioError({
148
+ code: StudioErrorCode.LOCALE_NOT_CONFIGURED,
149
+ headline: `Contentstack did not find the language "${locale}" on this stack. The locale came from the SDK configuration.`,
150
+ causes: localeCauses(locale),
151
+ context,
152
+ findings: { locale, localeSource: "configuration", status, errorCode },
153
+ });
154
+ }
155
+ function classifyResponseError(err, config, request = {}) {
156
+ const status = getStatusCode(err);
157
+ const errorCode = err?.error_code;
158
+ const errorMessage = err?.error_message ?? "";
159
+ const context = buildStudioErrorContext(config, request.servedBy);
160
+ // The response is identical whether the key is wrong or the host is for
161
+ // another region, so the two are ranked rather than picked between.
162
+ if (status === HttpStatus.PRECONDITION_FAILED &&
163
+ errorCode === ContentstackErrorCode.STACK_NOT_FOUND) {
164
+ return createStudioError({
165
+ code: StudioErrorCode.STACK_NOT_FOUND_ON_HOST,
166
+ headline: `Contentstack did not find a stack for this API key on ${context.host ?? "this host"}.`,
167
+ causes: stackNotFoundCauses(context.host),
168
+ context,
169
+ findings: { status, errorCode },
170
+ });
171
+ }
172
+ if (status === HttpStatus.UNPROCESSABLE_ENTITY &&
173
+ errorCode === ContentstackErrorCode.ENTRY_NOT_FOUND) {
174
+ if (ENVIRONMENT_NOT_FOUND_MESSAGE.test(errorMessage)) {
175
+ return environmentNotFound(context, status, errorCode);
176
+ }
177
+ if (LANGUAGE_NOT_FOUND_MESSAGE.test(errorMessage)) {
178
+ const locale = request.locale ?? context.locale ?? "";
179
+ // Split on provenance: a configured locale is a setup fault, one from the
180
+ // address is visitor input. Getting it wrong 5xxs anyone who mistypes.
181
+ return request.localeSource === "url-pattern"
182
+ ? urlLocaleNotFound(locale, request.url, context, status, errorCode)
183
+ : localeNotConfigured(locale, context, status, errorCode);
184
+ }
185
+ // Any other 141 is left alone deliberately. A missing entry is the only
186
+ // meaning that occurs in ordinary traffic, so an unrecognised wording is
187
+ // most likely one — and 5xx-ing instead breaks every genuine missing page
188
+ // the day Contentstack rewords a string.
189
+ }
190
+ if (status === HttpStatus.UNPROCESSABLE_ENTITY &&
191
+ errorCode === ContentstackErrorCode.CONTENT_TYPE_NOT_FOUND) {
192
+ return createStudioError({
193
+ code: StudioErrorCode.CONTENT_TYPE_NOT_FOUND,
194
+ headline: `The content type "${config.contentTypeUid}" does not exist in this stack.`,
195
+ causes: contentTypeCauses(config),
196
+ context,
197
+ findings: {
198
+ contentTypeUid: config.contentTypeUid,
199
+ contentTypeUidWasSupplied: config.contentTypeUidWasSupplied,
200
+ },
201
+ });
202
+ }
203
+ return undefined;
204
+ }
205
+ /**
206
+ * The diagnosis for a response nothing above recognised.
207
+ *
208
+ * **Deliberately not folded into `classifyResponseError`.** That function
209
+ * returns `undefined` on purpose for an unrecognised 141, so the caller's own
210
+ * not-found reading gets a chance — a missing entry is the only meaning of a
211
+ * 141 that occurs in ordinary traffic. Making the classifier total instead
212
+ * turns every genuine missing page into a server error the day Contentstack
213
+ * rewords a string, which is the failure this whole contract exists to remove.
214
+ *
215
+ * So the terminal case lives here, and a call site reaches it only after it has
216
+ * settled whether absence is a possible answer for the request it made.
217
+ */
218
+ function diagnoseUnreadableResponse(err, config, request = {},
219
+ /**
220
+ * What "there is no such page" means for the request that failed.
221
+ *
222
+ * The caller supplies it because only the caller knows what it asked for: an
223
+ * address that matches nothing and a uid that matches nothing are different
224
+ * findings taking opposite advice. Omit it where absence is not a possible
225
+ * answer, and an entry-not-found is then reported as the server error it
226
+ * literally is.
227
+ */
228
+ notFound) {
229
+ const status = getStatusCode(err);
230
+ const errorCode = err?.error_code;
231
+ const context = buildStudioErrorContext(config, request.servedBy);
232
+ // An unplaceable 141 reads as a missing entry, which is the only one of its
233
+ // four meanings that occurs in ordinary traffic. Reporting it as a server
234
+ // error instead would 5xx every genuine missing page the day Contentstack
235
+ // rewords a string — so the caller's own not-found wins where it has one.
236
+ const readsAsMissing = status === HttpStatus.NOT_FOUND ||
237
+ (status === HttpStatus.UNPROCESSABLE_ENTITY &&
238
+ errorCode === ContentstackErrorCode.ENTRY_NOT_FOUND);
239
+ if (readsAsMissing && notFound)
240
+ return notFound();
241
+ if (status === undefined && isNetworkError(err)) {
242
+ return createStudioError({
243
+ code: StudioErrorCode.TRANSPORT_FAILED,
244
+ headline: `The request to ${context.host ?? "Contentstack"} did not complete.`,
245
+ causes: transportCauses(context.host),
246
+ context,
247
+ findings: {
248
+ host: context.host,
249
+ detail: err?.message,
250
+ },
251
+ });
252
+ }
253
+ return createStudioError({
254
+ code: StudioErrorCode.UPSTREAM_ERROR,
255
+ headline: status === undefined
256
+ ? "Contentstack's reply to this request could not be read."
257
+ : `Contentstack answered this request with ${status}.`,
258
+ causes: [
259
+ {
260
+ cause: "Contentstack could not answer this request.",
261
+ fix: "Retry. If it persists, report it with the status and code below.",
262
+ },
263
+ ],
264
+ context,
265
+ findings: { status, errorCode, host: context.host },
266
+ });
267
+ }
268
+ /**
269
+ * Nothing answered, so there is nothing about the project to blame. Ordered by
270
+ * what the reader can act on: their own network and their own host first.
271
+ */
272
+ function transportCauses(host) {
273
+ return [
274
+ {
275
+ cause: "The network between this site and Contentstack dropped the request.",
276
+ fix: "Retry. If it keeps happening, check outbound network access and any proxy in front of this site.",
277
+ },
278
+ {
279
+ cause: host
280
+ ? `Nothing is listening at ${host}, or it is blocked from where this site runs.`
281
+ : "The configured Contentstack address cannot be reached from where this site runs.",
282
+ fix: "Check the address, and that it is reachable from this environment.",
283
+ },
284
+ ];
285
+ }
286
+
287
+ export { classifyResponseError, diagnoseUnreadableResponse };
288
+ //# sourceMappingURL=classify-response-error.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"classify-response-error.js","sources":["../../src/utils/classify-response-error.ts"],"sourcesContent":[null],"names":[],"mappings":"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"}
@@ -1,30 +1,46 @@
1
- const ComposableStudioErrors = {
2
- COMPOSITION_NOT_FOUND: "COMPOSITION_NOT_FOUND",
3
- COMPOSITION_NOT_FOUND_BY_URL: "COMPOSITION_NOT_FOUND_BY_URL",
4
- PREVIEW_ENTRY_NOT_FOUND: "PREVIEW_ENTRY_NOT_FOUND",
5
- FETCHING_CONNECTED_DATA_FAILED: "FETCHING_CONNECTED_DATA_FAILED",
6
- RESOLVING_DATA_SOURCES_FAILED: "RESOLVING_DATA_SOURCES_FAILED",
7
- STACK_SDK_NOT_AVAILABLE: "STACK_SDK_NOT_AVAILABLE",
8
- INVALID_FETCH_SPEC_OPTIONS: "INVALID_FETCH_SPEC_OPTIONS",
9
- MISSING_COMPOSITION_IDENTIFIER: "MISSING_COMPOSITION_IDENTIFIER",
10
- UI_PARSING_ERROR: "UI_PARSING_ERROR",
11
- SPEC_DATA_INVALID: "SPEC_DATA_INVALID",
12
- NETWORK_ERROR: "NETWORK_ERROR",
13
- AUTHENTICATION_ERROR: "AUTHENTICATION_ERROR",
14
- SERVER_ERROR: "SERVER_ERROR",
15
- COMPONENT_NOT_FOUND: "COMPONENT_NOT_FOUND",
16
- };
1
+ import { ERROR_CLASS } from './studio-error-codes.js';
2
+
17
3
  class ComposableStudioError extends Error {
18
- id;
19
4
  details;
20
- constructor(id, message, details) {
5
+ /**
6
+ * The case this error is, and the identifier everything new reads: the log
7
+ * line, the docs, a support conversation, and the diagnostic Studio receives.
8
+ *
9
+ * Optional while throw sites move over one at a time. Absent means the site
10
+ * that raised it has not been diagnosed yet, not that the case is unknown.
11
+ * `id` is what those sites still carry, and it goes once they have all moved.
12
+ */
13
+ code;
14
+ /**
15
+ * What to do, ordered, most likely first. One entry means we proved the
16
+ * cause; more than one means we are ranking and the reader should work down
17
+ * the list. Set together with `code`, and never empty when set.
18
+ */
19
+ causes;
20
+ /** Where the request went and what it was made with. Never a token. */
21
+ context;
22
+ /**
23
+ * What this particular failure established, typed by `code`. Separate from
24
+ * `details`, which is the legacy metadata bag: these are the facts a surface
25
+ * reads, and the shape is closed so no throw site can add a token to it.
26
+ */
27
+ findings;
28
+ /**
29
+ * Which of the five classes this code belongs to, looked up rather than
30
+ * stored, so it can never disagree with `code`. A surface that does not
31
+ * recognise the code can still act on the class — it is the coarse answer
32
+ * that stays true for every code added after that surface shipped.
33
+ */
34
+ get errorClass() {
35
+ return this.code ? ERROR_CLASS[this.code] : undefined;
36
+ }
37
+ constructor(message, details) {
21
38
  super(message);
22
- this.id = id;
23
39
  this.details = details;
24
40
  }
25
41
  }
26
42
  // This fails for agadoo
27
43
  // ComposableStudioError.prototype.name = "ComposableStudioError";
28
44
 
29
- export { ComposableStudioError, ComposableStudioErrors };
45
+ export { ComposableStudioError };
30
46
  //# sourceMappingURL=composable-studio-error.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"composable-studio-error.js","sources":["../../src/utils/composable-studio-error.ts"],"sourcesContent":[null],"names":[],"mappings":"AAAO,MAAM,sBAAsB,GAAG;AACpC,IAAA,qBAAqB,EAAE,uBAAuB;AAC9C,IAAA,4BAA4B,EAAE,8BAA8B;AAC5D,IAAA,uBAAuB,EAAE,yBAAyB;AAClD,IAAA,8BAA8B,EAAE,gCAAgC;AAChE,IAAA,6BAA6B,EAAE,+BAA+B;AAC9D,IAAA,uBAAuB,EAAE,yBAAyB;AAClD,IAAA,0BAA0B,EAAE,4BAA4B;AACxD,IAAA,8BAA8B,EAAE,gCAAgC;AAChE,IAAA,gBAAgB,EAAE,kBAAkB;AACpC,IAAA,iBAAiB,EAAE,mBAAmB;AACtC,IAAA,aAAa,EAAE,eAAe;AAC9B,IAAA,oBAAoB,EAAE,sBAAsB;AAC5C,IAAA,YAAY,EAAE,cAAc;AAC5B,IAAA,mBAAmB,EAAE,qBAAqB;;AA+BtC,MAAO,qBAAsB,SAAQ,KAAK,CAAA;AAC9C,IAAA,EAAE;AACF,IAAA,OAAO;AAEP,IAAA,WAAA,CACE,EAAuC,EACvC,OAAe,EACf,OAAsC,EAAA;QAEtC,KAAK,CAAC,OAAO,CAAC;AACd,QAAA,IAAI,CAAC,EAAE,GAAG,EAAE;AACZ,QAAA,IAAI,CAAC,OAAO,GAAG,OAAO;IACxB;AACD;AACD;AACA;;;;"}
1
+ {"version":3,"file":"composable-studio-error.js","sources":["../../src/utils/composable-studio-error.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAoCM,MAAO,qBAAsB,SAAQ,KAAK,CAAA;AAC9C,IAAA,OAAO;AAEP;;;;;;;AAOG;AACH,IAAA,IAAI;AAEJ;;;;AAIG;AACH,IAAA,MAAM;;AAGN,IAAA,OAAO;AACP;;;;AAIG;AACH,IAAA,QAAQ;AAER;;;;;AAKG;AACH,IAAA,IAAI,UAAU,GAAA;AACZ,QAAA,OAAO,IAAI,CAAC,IAAI,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,SAAS;IACvD;IAEA,WAAA,CAAY,OAAe,EAAE,OAAsC,EAAA;QACjE,KAAK,CAAC,OAAO,CAAC;AACd,QAAA,IAAI,CAAC,OAAO,GAAG,OAAO;IACxB;AACD;AACD;AACA;;;;"}
@@ -0,0 +1,52 @@
1
+ import { ComposableStudioError } from './composable-studio-error.js';
2
+ import { ERROR_CLASS, StudioErrorClass } from './studio-error-codes.js';
3
+
4
+ /**
5
+ * How a host tells "there is no such page" from "we could not answer".
6
+ *
7
+ * A host rendering a composition answers one question per request: render this,
8
+ * return 404, or return 5xx. Only one kind of failure is a 404, and getting it
9
+ * wrong is expensive in one direction — a 404 is acted on permanently by crawlers
10
+ * and caches, while a 5xx is retried.
11
+ */
12
+ /** Every code that means we looked, finished looking, and nothing matched. */
13
+ const NOT_FOUND_CODES = new Set(Object.keys(ERROR_CLASS).filter((code) => ERROR_CLASS[code] === StudioErrorClass.NOT_FOUND));
14
+ /**
15
+ * Whether this failure means the page is not there.
16
+ *
17
+ * **This is the check to write, rather than `instanceof`.** Two copies of the
18
+ * package in one dependency tree is an ordinary outcome of a transitive install,
19
+ * and each copy has its own class object — so a prototype check returns false for
20
+ * an error raised by the other copy. It fails silently and in the worst direction:
21
+ * a genuinely missing page is reported as a server error, and the host serves a
22
+ * 500 where it meant to serve a 404.
23
+ *
24
+ * A code is a string. It survives the package boundary, a structured-clone, a
25
+ * serialisation to a log and back, and a second copy of the SDK.
26
+ */
27
+ function isCompositionNotFound(error) {
28
+ if (typeof error !== "object" || error === null)
29
+ return false;
30
+ const code = error.code;
31
+ return typeof code === "string" && NOT_FOUND_CODES.has(code);
32
+ }
33
+ /**
34
+ * The not-found subclass, for a host that would rather catch by type.
35
+ *
36
+ * It ships because catching by type is a reasonable thing to want, and because an
37
+ * error's class is what a debugger and a stack trace show. It is not the
38
+ * documented check: see {@link isCompositionNotFound} for why.
39
+ *
40
+ * Nothing constructs this directly. The diagnosis factory picks it whenever the
41
+ * code it is given belongs to the not-found class, which is what keeps the class
42
+ * and the predicate from ever disagreeing about the same error.
43
+ */
44
+ class CompositionNotFoundError extends ComposableStudioError {
45
+ }
46
+ /** Whether a code belongs to the not-found class, for the factory's own use. */
47
+ function codeIsNotFound(code) {
48
+ return NOT_FOUND_CODES.has(code);
49
+ }
50
+
51
+ export { CompositionNotFoundError, codeIsNotFound, isCompositionNotFound };
52
+ //# sourceMappingURL=composition-not-found.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"composition-not-found.js","sources":["../../src/utils/composition-not-found.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAAA;;;;;;;AAOG;AASH;AACA,MAAM,eAAe,GAAwB,IAAI,GAAG,CAClD,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,CAC7B,CAAC,IAAI,KACH,WAAW,CAAC,IAA2B,CAAC,KAAK,gBAAgB,CAAC,SAAS,CAC1E,CACF;AAED;;;;;;;;;;;;AAYG;AACG,SAAU,qBAAqB,CAAC,KAAc,EAAA;AAClD,IAAA,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;AAAE,QAAA,OAAO,KAAK;AAC7D,IAAA,MAAM,IAAI,GAAI,KAA4B,CAAC,IAAI;IAC/C,OAAO,OAAO,IAAI,KAAK,QAAQ,IAAI,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC;AAC9D;AAEA;;;;;;;;;;AAUG;AACG,MAAO,wBAAyB,SAAQ,qBAAqB,CAAA;AAAG;AAEtE;AACM,SAAU,cAAc,CAAC,IAAyB,EAAA;AACtD,IAAA,OAAO,eAAe,CAAC,GAAG,CAAC,IAAI,CAAC;AAClC;;;;"}
@@ -22,8 +22,27 @@ const isBrowser = () => {
22
22
  */
23
23
  const INCLUDE_DEPTH_COUNT = 3;
24
24
  // SDK Version constants for Studio Intelligence
25
- const SDK_VERSION = "3.2.0-alpha-9e6cc9b.0";
26
- const SCHEMA_VERSION = "1.0.0";
25
+ const SDK_VERSION = "4.0.0-alpha-d9df7dd.0";
26
+ /**
27
+ * Version of the composition spec this SDK writes and reads.
28
+ *
29
+ * Studio persists whatever the canvas SDK reports here onto the composition as
30
+ * `schema_version`, so it doubles as a marker of what a saved composition can be
31
+ * trusted to contain.
32
+ *
33
+ * 1.1.0 (COMPLETE_INCLUDES_FROM_SCHEMA_VERSION) — every fetch root's
34
+ * `data_sources[*].resolvedReferences` is recomputed on save and holds exactly
35
+ * the references it needs, including what this SDK used to work out at render
36
+ * (`derivePlacementIncludePaths`), so the SDK derives nothing (ADR 0018). Below
37
+ * that the sets were accumulated by union, and before 2026-07-17 they held only
38
+ * what the author had ticked — which is why the derivation still runs for them.
39
+ *
40
+ * RELEASE ORDER: released only after Studio saves complete sets for every fetch
41
+ * root (studio-ui#1303, which calls `derivePlacementIncludePaths` at save). An SDK
42
+ * reporting 1.1.0 to a Studio that does not yet do that would mark compositions
43
+ * as trustworthy when they are not.
44
+ */
45
+ const SCHEMA_VERSION = "1.1.0";
27
46
  const COMPOSABLE_DATA_ATTRIBUTES = {
28
47
  BUILDER: "data-composable-studio-builder",
29
48
  PLACEHOLDER: "data-composable-studio-placeholder",
@@ -1 +1 @@
1
- {"version":3,"file":"constants.js","sources":["../../src/utils/constants.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAEO,MAAM,SAAS,GAAG,MAAK;IAC5B,OAAO,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,MAAM,KAAK,WAAW;AACvE;AAEA;;;;;;;;;;;;;;;;AAgBG;AACI,MAAM,mBAAmB,GAAG;AAEnC;MACa,WAAW,GAAG;AACpB,MAAM,cAAc,GAAG;AAEvB,MAAM,0BAA0B,GAAG;AACxC,IAAA,OAAO,EAAE,gCAAgC;AACzC,IAAA,WAAW,EAAE,oCAAoC;AACjD,IAAA,IAAI,EAAE,6BAA6B;AACnC,IAAA,IAAI,EAAE,6BAA6B;AACnC,IAAA,IAAI,EAAE,6BAA6B;AACnC,IAAA,EAAE,EAAE,2BAA2B;AAC/B,IAAA,QAAQ,EAAE,iCAAiC;AAC3C,IAAA,IAAI,EAAE,WAAW;;;;;"}
1
+ {"version":3,"file":"constants.js","sources":["../../src/utils/constants.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAEO,MAAM,SAAS,GAAG,MAAK;IAC5B,OAAO,OAAO,MAAM,KAAK,WAAW,IAAI,OAAO,MAAM,KAAK,WAAW;AACvE;AAEA;;;;;;;;;;;;;;;;AAgBG;AACI,MAAM,mBAAmB,GAAG;AAEnC;MACa,WAAW,GAAG;AAC3B;;;;;;;;;;;;;;;;;;AAkBG;AACI,MAAM,cAAc,GAAG;AAEvB,MAAM,0BAA0B,GAAG;AACxC,IAAA,OAAO,EAAE,gCAAgC;AACzC,IAAA,WAAW,EAAE,oCAAoC;AACjD,IAAA,IAAI,EAAE,6BAA6B;AACnC,IAAA,IAAI,EAAE,6BAA6B;AACnC,IAAA,IAAI,EAAE,6BAA6B;AACnC,IAAA,EAAE,EAAE,2BAA2B;AAC/B,IAAA,QAAQ,EAAE,iCAAiC;AAC3C,IAAA,IAAI,EAAE,WAAW;;;;;"}
@@ -0,0 +1,166 @@
1
+ import { renderStudioErrorMessage } from './studio-error.js';
2
+
3
+ /**
4
+ * The findings that are not errors: the page rendered, and something on it is
5
+ * wrong.
6
+ *
7
+ * The cut is the one drawn by [the setup-before-the-request decision]: a fault
8
+ * that stopped the composition loading is fatal and is raised as an error, and a
9
+ * fault that left the page working is never an error anywhere. These are the
10
+ * second kind. **None of them throws**, because throwing hands the application an
11
+ * error and an application with an error renders its 500 page in place of a site
12
+ * that works.
13
+ *
14
+ * So they log, and logging is the whole of the contract. They are not on the
15
+ * diagnostic Studio receives: nothing reads them there, and the two findings a
16
+ * surface does act on are derived by comparing values Studio already holds rather
17
+ * than reported from here. A channel with no sender and no receiver is a guess
18
+ * about a design nobody has done yet.
19
+ *
20
+ * **They draw no cards either.** A blank element, an empty list and an
21
+ * unresolved reference all show themselves on the page, and a popover apiece
22
+ * would teach an author to dismiss the popover on sight — including the one that
23
+ * says their api key is wrong.
24
+ */
25
+ /**
26
+ * The cases where the page came up and the content did not.
27
+ *
28
+ * A code is the identifier a developer reads in the log line and quotes in a
29
+ * support conversation, so it is stable once published — the same rule the error
30
+ * codes follow. Nothing branches on these, because nothing receives them.
31
+ */
32
+ const DegradedCode = {
33
+ /**
34
+ * A reference field came back as a two-key stub rather than as the entry it
35
+ * points at, so anything bound past that point has nothing to read.
36
+ *
37
+ * Either the composition nests deeper than one request can follow, or the
38
+ * entry it points at was deleted. Both produce the identical shape, so this
39
+ * names the symptom and ranks the two rather than asserting either.
40
+ */
41
+ REFERENCES_UNRESOLVED: "REFERENCES_UNRESOLVED",
42
+ /**
43
+ * A binding reads a path that does not exist on the entry we hold.
44
+ *
45
+ * Ambiguous on purpose. A renamed or deleted field and a field the author has
46
+ * simply left empty are indistinguishable from here — we hold the entry, not
47
+ * the content type's schema — so this carries both causes and asserts
48
+ * neither.
49
+ */
50
+ BINDING_PATH_MISSING: "BINDING_PATH_MISSING",
51
+ /**
52
+ * A binding that reads one value resolved to a group or a repeating block.
53
+ *
54
+ * Provable from the value's own type, so unlike the case above this one is
55
+ * asserted: the field the binding points at holds a different kind of value
56
+ * than the element can show. Usually the binding was pointed at a container
57
+ * rather than at a field inside it.
58
+ */
59
+ BINDING_SHAPE_MISMATCH: "BINDING_SHAPE_MISMATCH",
60
+ /**
61
+ * Fewer entries came back than were asked for, so the elements bound to the
62
+ * missing ones have nothing to read.
63
+ *
64
+ * A comparison of uids in memory, and worth making because the failure is
65
+ * otherwise silent — a batch that quietly drops one entry looks exactly like a
66
+ * page where one element was never bound.
67
+ */
68
+ FEWER_ENTRIES_THAN_REQUESTED: "FEWER_ENTRIES_THAN_REQUESTED",
69
+ /**
70
+ * A query data source ran and matched nothing.
71
+ *
72
+ * Not a failure by any measure available here — a filter that matches nothing
73
+ * today may match tomorrow — which is why it carries no causes and states only
74
+ * what happened. It is reported because "why is my product list empty" is the
75
+ * question this whole group exists to answer.
76
+ */
77
+ QUERY_RETURNED_NO_ROWS: "QUERY_RETURNED_NO_ROWS",
78
+ /**
79
+ * An asset read through a dotted projection came back null on the preview
80
+ * service, on a request that also projected a bare field.
81
+ *
82
+ * A verified Preview API defect rather than anything in the project: the same
83
+ * request against the delivery CDN returns the asset. It takes the place of
84
+ * the missing-binding report when its conditions hold, because the two look
85
+ * identical and only this one stops an author rebuilding a binding that was
86
+ * never broken.
87
+ *
88
+ * It ranks rather than asserts. The defect also needs the other projected
89
+ * field to be a modular block, and nothing here holds the content type's
90
+ * schema to check that, so the second cause stays on the list.
91
+ */
92
+ PREVIEW_ASSET_PROJECTION_NULL: "PREVIEW_ASSET_PROJECTION_NULL",
93
+ /**
94
+ * A query data source's request did not complete, so its list is empty for a
95
+ * reason that has nothing to do with its filters.
96
+ *
97
+ * The sibling of the case above and the reason that one can be trusted. Both
98
+ * end with an empty list on the page, and telling them apart is the whole
99
+ * point: one says "nothing matched", which sends an author to their filters,
100
+ * and this one says the question was never answered, which is nobody's
101
+ * content problem.
102
+ */
103
+ QUERY_REQUEST_FAILED: "QUERY_REQUEST_FAILED",
104
+ /**
105
+ * A composition's stored data sources will not parse, so none of its queries
106
+ * ran and every element bound to one is blank.
107
+ *
108
+ * Ours to fix, like the layout case, and named with the composition it belongs
109
+ * to so the reader can tell which page in a project is affected. Not fatal:
110
+ * the layout still rendered, and taking the page down over it would turn a
111
+ * partly-empty page into no page at all.
112
+ */
113
+ DATA_SOURCES_UNREADABLE: "DATA_SOURCES_UNREADABLE",
114
+ };
115
+ /**
116
+ * Whether this finding has already been reported on this page.
117
+ *
118
+ * These findings repeat: a binding inside a repeater resolves once per item, and
119
+ * a section's references are walked once per instance. Reporting each time turns
120
+ * one fact into fifty lines and buries whatever else the console had to say. The
121
+ * key is the rendered message, so two findings collapse only when a reader could
122
+ * not have told them apart anyway.
123
+ *
124
+ * Module-scoped, which is the same lifetime as the page: a reload starts over,
125
+ * which is what someone re-running a broken page expects.
126
+ */
127
+ const alreadyReported = new Set();
128
+ /**
129
+ * Whether the console should hear about any of this at all.
130
+ *
131
+ * On in development, because that is where somebody is looking. Off in
132
+ * production, because a customer's production console is theirs and not a place
133
+ * to put our warnings — unless their developer asks for it with `debug`, which is
134
+ * the only way to diagnose a deployed site that has no Studio chrome on it.
135
+ *
136
+ * Exported because two of these findings cost something to detect — one walks
137
+ * the whole fetched entry tree, one walks every binding — and doing that work
138
+ * to build a report nobody will read is a tax on every page that is fine. A
139
+ * site running in production pays for neither.
140
+ */
141
+ function degradedReportingIsOn(options) {
142
+ if (options?.debug === true)
143
+ return true;
144
+ return process.env.NODE_ENV === "development";
145
+ }
146
+ /**
147
+ * Reports a finding that did not stop the page.
148
+ *
149
+ * The message carries the code, the sentence and every cause, because a console
150
+ * shows the first argument and nothing else. The findings go alongside as an
151
+ * object rather than flattened into the prose: one collapsed row a reader opens
152
+ * when they want it, and one that copies as structured data rather than as text
153
+ * somebody has to parse back.
154
+ */
155
+ function reportDegraded(input, options) {
156
+ if (!degradedReportingIsOn(options))
157
+ return;
158
+ const message = renderStudioErrorMessage(input);
159
+ if (alreadyReported.has(message))
160
+ return;
161
+ alreadyReported.add(message);
162
+ console.warn(message, input.findings);
163
+ }
164
+
165
+ export { DegradedCode, degradedReportingIsOn, reportDegraded };
166
+ //# sourceMappingURL=degraded-finding.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"degraded-finding.js","sources":["../../src/utils/degraded-finding.ts"],"sourcesContent":[null],"names":[],"mappings":";;AAAA;;;;;;;;;;;;;;;;;;;;;AAqBG;AAMH;;;;;;AAMG;AACI,MAAM,YAAY,GAAG;AAC1B;;;;;;;AAOG;AACH,IAAA,qBAAqB,EAAE,uBAAuB;AAC9C;;;;;;;AAOG;AACH,IAAA,oBAAoB,EAAE,sBAAsB;AAC5C;;;;;;;AAOG;AACH,IAAA,sBAAsB,EAAE,wBAAwB;AAChD;;;;;;;AAOG;AACH,IAAA,4BAA4B,EAAE,8BAA8B;AAC5D;;;;;;;AAOG;AACH,IAAA,sBAAsB,EAAE,wBAAwB;AAChD;;;;;;;;;;;;;AAaG;AACH,IAAA,6BAA6B,EAAE,+BAA+B;AAC9D;;;;;;;;;AASG;AACH,IAAA,oBAAoB,EAAE,sBAAsB;AAC5C;;;;;;;;AAQG;AACH,IAAA,uBAAuB,EAAE,yBAAyB;;AAoGpD;;;;;;;;;;;AAWG;AACH,MAAM,eAAe,GAAG,IAAI,GAAG,EAAU;AAOzC;;;;;;;;;;;;AAYG;AACG,SAAU,qBAAqB,CACnC,OAA+B,EAAA;AAE/B,IAAA,IAAI,OAAO,EAAE,KAAK,KAAK,IAAI;AAAE,QAAA,OAAO,IAAI;AACxC,IAAA,OAAO,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,aAAa;AAC/C;AAEA;;;;;;;;AAQG;AACG,SAAU,cAAc,CAC5B,KAA8B,EAC9B,OAA+B,EAAA;AAE/B,IAAA,IAAI,CAAC,qBAAqB,CAAC,OAAO,CAAC;QAAE;AAErC,IAAA,MAAM,OAAO,GAAG,wBAAwB,CAAC,KAAK,CAAC;AAC/C,IAAA,IAAI,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC;QAAE;AAClC,IAAA,eAAe,CAAC,GAAG,CAAC,OAAO,CAAC;IAE5B,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,KAAK,CAAC,QAAQ,CAAC;AACvC;;;;"}
@@ -1,4 +1,4 @@
1
- import { COMPOSABLE_STUDIO_QUERY_PARAM, IS_BROWSER } from '@contentstack/studio-messenger';
1
+ import { COMPOSABLE_STUDIO_QUERY_PARAM, IS_BROWSER } from '@contentstack/studio-messenger/constants';
2
2
 
3
3
  /**
4
4
  * Stable editor-mode detection contract.