drupal-canvas 0.6.0 → 0.7.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/dist/index.d.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import FormattedText from "./FormattedText.js";
2
- import { getPageData, getSiteData, sortMenu } from "./drupal-utils.js";
3
- import { t as CanvasJsonApiClient } from "./jsonapi-client-Q84JvzCD.js";
2
+ import { a as ThemeAssets, c as getSiteData, d as PageContext, f as SiteContext, i as SiteData, l as sortMenu, n as EntityMetadata, o as TranslationMetadata, r as PageData, s as getPageData, t as BreadcrumbLink, u as CanvasContext } from "./drupal-utils-CUaK4jOk.js";
3
+ import "./context-Cb4HbPbR.js";
4
+ import { a as LegacyJsonApiClient, i as JsonApiRuntimeConfig, n as DraftSessionError, o as createJsonApiClient, r as JsonApiClientConfig, s as isDraftSessionError, t as CanvasJsonApiClient } from "./jsonapi-client-BAQ3V5CC.js";
4
5
  import { getNodePath, sortMenu as sortMenu$1 } from "./jsonapi-utils.js";
5
6
  import Image from "./next-image-standalone.js";
6
7
  import { cn } from "./utils.js";
@@ -101,17 +102,126 @@ declare function canvasFormatDateRange<T extends {
101
102
  to?: string | null;
102
103
  } | null | undefined>(range: T, options?: Pick<CanvasDateFormatOptions, 'dateStyle'>): T;
103
104
  //#endregion
105
+ //#region src/drupal-settings.d.ts
106
+ /** The subset of `drupalSettings.canvasData.v0` the context API reads. */
107
+ interface CanvasDataV0 {
108
+ pageTitle?: string | null;
109
+ breadcrumbs?: CanvasContext['page'] extends (infer P) ? P extends {
110
+ breadcrumbs: infer B;
111
+ } ? B | null : never : never;
112
+ mainEntity?: NonNullable<CanvasContext['page']>['mainEntity'];
113
+ branding?: NonNullable<CanvasContext['site']>['branding'] | null;
114
+ baseUrl?: string | null;
115
+ themeAssets?: NonNullable<CanvasContext['site']>['themeAssets'] | null;
116
+ jsonapiSettings?: {
117
+ apiPrefix?: string;
118
+ } | null;
119
+ }
120
+ interface DrupalSettingsLike {
121
+ canvasData?: {
122
+ v0?: CanvasDataV0 | null;
123
+ } | null;
124
+ }
125
+ /** Reads `drupalSettings.canvasData.v0` from a settings object or the global. */
126
+ declare function readCanvasDataV0(settings?: DrupalSettingsLike | undefined): CanvasDataV0 | null;
127
+ /**
128
+ * Builds the page and site context from `drupalSettings.canvasData.v0`.
129
+ *
130
+ * Page context is available when Drupal attached any page-level key
131
+ * (`pageTitle`, `breadcrumbs`, or `mainEntity`); site context when it attached
132
+ * `branding`. Missing keys inside an available group take the same defaults
133
+ * as the legacy getters.
134
+ */
135
+ declare function drupalSettingsToCanvasContext(v0: CanvasDataV0 | null | undefined): CanvasContext;
136
+ /**
137
+ * Builds the JSON:API runtime configuration for a Drupal-rendered page from
138
+ * `drupalSettings.canvasData.v0`, or `null` when the settings do not carry a
139
+ * base URL or JSON:API is not installed. Previews read working copies through
140
+ * the editor's Drupal session.
141
+ */
142
+ declare function drupalSettingsToJsonApiRuntimeConfig(v0: CanvasDataV0 | null | undefined, options?: {
143
+ preview?: boolean;
144
+ }): JsonApiRuntimeConfig | null;
145
+ //#endregion
146
+ //#region src/migration.d.ts
147
+ /**
148
+ * @file
149
+ * Migration guidance shared by the legacy API errors, the hook warnings, and
150
+ * the Canvas CLI's pull codemod report.
151
+ */
152
+ /**
153
+ * The AI-agent migration prompt included in legacy API errors and printed by
154
+ * the Canvas CLI for components it could not migrate automatically.
155
+ */
156
+ declare const AGENT_MIGRATION_PROMPT: string;
157
+ /** Replacement guidance per legacy API. */
158
+ declare const LEGACY_API_GUIDANCE: {
159
+ readonly 'getPageData()': string;
160
+ readonly 'getSiteData()': string;
161
+ readonly 'new JsonApiClient()': string;
162
+ };
163
+ type LegacyApiName = keyof typeof LEGACY_API_GUIDANCE;
164
+ /**
165
+ * Builds the error message thrown when a legacy API is invoked outside Drupal
166
+ * and Workbench.
167
+ */
168
+ declare function formatLegacyApiError(api: LegacyApiName): string;
169
+ //#endregion
104
170
  //#region src/Region.d.ts
105
171
  type RegionsMap = Record<string, ReactNode>;
106
172
  type RegionsProviderProps = {
107
173
  regions: RegionsMap;
108
174
  children: ReactNode;
109
175
  };
176
+ /**
177
+ * Supplies the region node map read by `Region`.
178
+ *
179
+ * @deprecated Theme-global regions were replaced by page variants (ADR 19);
180
+ * compose pages with the component tree instead. Kept for compatibility.
181
+ */
110
182
  declare function RegionsProvider({ regions, children }: RegionsProviderProps): import("react/jsx-runtime").JSX.Element;
111
183
  type RegionProps = {
112
184
  name: string;
113
185
  fallback?: ReactNode;
114
186
  };
187
+ /**
188
+ * Renders the region whose machine name matches `name`.
189
+ *
190
+ * @deprecated Theme-global regions were replaced by page variants (ADR 19);
191
+ * compose pages with the component tree instead. Kept for compatibility.
192
+ */
115
193
  declare function Region({ name, fallback }: RegionProps): import("react/jsx-runtime").JSX.Element;
116
194
  //#endregion
117
- export { type CanvasDateFormatOptions, FormattedText, Image, CanvasJsonApiClient as JsonApiClient, Region, RegionsProvider, canvasFormatDate, canvasFormatDateRange, canvasFormatDateTime, canvasFormatTime, cn, getNodePath, getPageData, getSiteData, sortMenu as sortLinksetMenu, sortMenu$1 as sortMenu };
195
+ //#region src/runtime.d.ts
196
+ /**
197
+ * @file
198
+ * The runtime marker that identifies the environments in which the legacy
199
+ * `getPageData()`, `getSiteData()`, and `new JsonApiClient()` APIs keep
200
+ * working: Drupal-rendered Code Components and Canvas Workbench previews.
201
+ *
202
+ * The marker is established explicitly by those integrations before any Code
203
+ * Component module is evaluated. It is a compatibility check, not a security
204
+ * boundary: the presence of `window`, a backend URL, or a user-created
205
+ * `drupalSettings` object is deliberately not treated as proof of either
206
+ * environment.
207
+ *
208
+ * @see docs/adr/0021-code-component-runtime-compatibility-across-frontend-modes.md
209
+ */
210
+ /** The environments that support the legacy runtime APIs. */
211
+ type CanvasRuntimeEnvironment = 'drupal' | 'workbench';
212
+ /**
213
+ * Declares the current runtime environment. Called by Drupal and Workbench
214
+ * integrations, never by Code Components or headless applications.
215
+ */
216
+ declare function declareCanvasRuntime(environment: CanvasRuntimeEnvironment): void;
217
+ /**
218
+ * Returns the declared runtime environment, or `null` outside Drupal and
219
+ * Workbench.
220
+ */
221
+ declare function getCanvasRuntime(): CanvasRuntimeEnvironment | null;
222
+ /**
223
+ * Whether the legacy runtime APIs are supported in the current environment.
224
+ */
225
+ declare function isLegacyRuntimeSupported(): boolean;
226
+ //#endregion
227
+ export { AGENT_MIGRATION_PROMPT, type BreadcrumbLink, type CanvasContext, type CanvasDataV0, type CanvasDateFormatOptions, type CanvasJsonApiClient, type CanvasRuntimeEnvironment, DraftSessionError, type EntityMetadata, FormattedText, Image, LegacyJsonApiClient as JsonApiClient, type JsonApiClientConfig, type JsonApiRuntimeConfig, LEGACY_API_GUIDANCE, type PageContext, type PageData, Region, RegionsProvider, type SiteContext, type SiteData, type ThemeAssets, type TranslationMetadata, canvasFormatDate, canvasFormatDateRange, canvasFormatDateTime, canvasFormatTime, cn, createJsonApiClient, declareCanvasRuntime, drupalSettingsToCanvasContext, drupalSettingsToJsonApiRuntimeConfig, formatLegacyApiError, getCanvasRuntime, getNodePath, getPageData, getSiteData, isDraftSessionError, isLegacyRuntimeSupported, readCanvasDataV0, sortMenu as sortLinksetMenu, sortMenu$1 as sortMenu };
package/dist/index.js CHANGED
@@ -1,6 +1,7 @@
1
+ import { a as declareCanvasRuntime, i as formatLegacyApiError, n as LEGACY_API_GUIDANCE, o as getCanvasRuntime, s as isLegacyRuntimeSupported, t as AGENT_MIGRATION_PROMPT } from "./migration-CPBzW78_.js";
1
2
  import { getPageData, getSiteData, sortMenu } from "./drupal-utils.js";
2
3
  import FormattedText from "./FormattedText.js";
3
- import { JsonApiClient as CanvasJsonApiClient } from "./jsonapi-client.js";
4
+ import { a as isDraftSessionError, i as createJsonApiClient, n as DraftSessionError, r as LegacyJsonApiClient } from "./jsonapi-client-CejP62bM.js";
4
5
  import { getNodePath, sortMenu as sortMenu$1 } from "./jsonapi-utils.js";
5
6
  import Image from "./next-image-standalone.js";
6
7
  import { cn } from "./utils.js";
@@ -148,17 +149,92 @@ function canvasFormatDateRange(range, options) {
148
149
  return result;
149
150
  }
150
151
  //#endregion
152
+ //#region src/drupal-settings.ts
153
+ /** Reads `drupalSettings.canvasData.v0` from a settings object or the global. */
154
+ function readCanvasDataV0(settings = globalThis.drupalSettings) {
155
+ const v0 = settings?.canvasData?.v0;
156
+ return v0 && typeof v0 === "object" ? v0 : null;
157
+ }
158
+ const EMPTY_THEME_ASSETS = {
159
+ logo: { url: "" },
160
+ favicon: {
161
+ url: "",
162
+ mimeType: ""
163
+ }
164
+ };
165
+ /**
166
+ * Builds the page and site context from `drupalSettings.canvasData.v0`.
167
+ *
168
+ * Page context is available when Drupal attached any page-level key
169
+ * (`pageTitle`, `breadcrumbs`, or `mainEntity`); site context when it attached
170
+ * `branding`. Missing keys inside an available group take the same defaults
171
+ * as the legacy getters.
172
+ */
173
+ function drupalSettingsToCanvasContext(v0) {
174
+ if (!v0) return {
175
+ page: null,
176
+ site: null
177
+ };
178
+ const hasPage = "pageTitle" in v0 || "breadcrumbs" in v0 || "mainEntity" in v0;
179
+ const hasSite = "branding" in v0;
180
+ return {
181
+ page: hasPage ? {
182
+ pageTitle: v0.pageTitle || "",
183
+ breadcrumbs: v0.breadcrumbs || [],
184
+ mainEntity: v0.mainEntity || null
185
+ } : null,
186
+ site: hasSite ? {
187
+ branding: v0.branding || {
188
+ homeUrl: "",
189
+ siteName: "",
190
+ siteSlogan: ""
191
+ },
192
+ baseUrl: v0.baseUrl || "/",
193
+ themeAssets: v0.themeAssets || EMPTY_THEME_ASSETS
194
+ } : null
195
+ };
196
+ }
197
+ /**
198
+ * Builds the JSON:API runtime configuration for a Drupal-rendered page from
199
+ * `drupalSettings.canvasData.v0`, or `null` when the settings do not carry a
200
+ * base URL or JSON:API is not installed. Previews read working copies through
201
+ * the editor's Drupal session.
202
+ */
203
+ function drupalSettingsToJsonApiRuntimeConfig(v0, options = {}) {
204
+ if (!v0 || typeof v0.baseUrl !== "string" || v0.baseUrl === "") return null;
205
+ if (v0.jsonapiSettings === null) return null;
206
+ const preview = options.preview ?? false;
207
+ return {
208
+ baseUrl: v0.baseUrl,
209
+ ...v0.jsonapiSettings?.apiPrefix && { apiPrefix: v0.jsonapiSettings.apiPrefix },
210
+ resourceVersion: preview ? "rel:working-copy" : null,
211
+ preview
212
+ };
213
+ }
214
+ //#endregion
151
215
  //#region src/Region.tsx
152
216
  const RegionsContext = createContext({});
217
+ /**
218
+ * Supplies the region node map read by `Region`.
219
+ *
220
+ * @deprecated Theme-global regions were replaced by page variants (ADR 19);
221
+ * compose pages with the component tree instead. Kept for compatibility.
222
+ */
153
223
  function RegionsProvider({ regions, children }) {
154
224
  return /* @__PURE__ */ jsx(RegionsContext.Provider, {
155
225
  value: regions,
156
226
  children
157
227
  });
158
228
  }
229
+ /**
230
+ * Renders the region whose machine name matches `name`.
231
+ *
232
+ * @deprecated Theme-global regions were replaced by page variants (ADR 19);
233
+ * compose pages with the component tree instead. Kept for compatibility.
234
+ */
159
235
  function Region({ name, fallback = null }) {
160
236
  const node = useContext(RegionsContext)[name];
161
237
  return /* @__PURE__ */ jsx(Fragment, { children: node ?? fallback });
162
238
  }
163
239
  //#endregion
164
- export { FormattedText, Image, CanvasJsonApiClient as JsonApiClient, Region, RegionsProvider, canvasFormatDate, canvasFormatDateRange, canvasFormatDateTime, canvasFormatTime, cn, getNodePath, getPageData, getSiteData, sortMenu as sortLinksetMenu, sortMenu$1 as sortMenu };
240
+ export { AGENT_MIGRATION_PROMPT, DraftSessionError, FormattedText, Image, LegacyJsonApiClient as JsonApiClient, LEGACY_API_GUIDANCE, Region, RegionsProvider, canvasFormatDate, canvasFormatDateRange, canvasFormatDateTime, canvasFormatTime, cn, createJsonApiClient, declareCanvasRuntime, drupalSettingsToCanvasContext, drupalSettingsToJsonApiRuntimeConfig, formatLegacyApiError, getCanvasRuntime, getNodePath, getPageData, getSiteData, isDraftSessionError, isLegacyRuntimeSupported, readCanvasDataV0, sortMenu as sortLinksetMenu, sortMenu$1 as sortMenu };
@@ -1,4 +1,4 @@
1
- import { ComponentType } from "react";
1
+ import { ComponentType, ReactNode } from "react";
2
2
  import { z } from "zod";
3
3
  import { Spec } from "@json-render/core";
4
4
  import { ComponentMetadata } from "@drupal-canvas/discovery";
@@ -59,7 +59,7 @@ type ComponentRegistry = Record<string, ComponentType<Record<string, unknown>>>;
59
59
  * @param registry - Component registry to use for rendering.
60
60
  * @see {@link defineComponentRegistry}
61
61
  */
62
- declare function renderSpec(spec: Spec, registry: ComponentRegistry): React.ReactNode;
62
+ declare function renderSpec(spec: Spec, registry: ComponentRegistry): ReactNode;
63
63
  /**
64
64
  * Renders a Drupal Canvas component tree.
65
65
  *
@@ -67,7 +67,7 @@ declare function renderSpec(spec: Spec, registry: ComponentRegistry): React.Reac
67
67
  * @param registry - Component registry to use for rendering.
68
68
  * @see {@link defineComponentRegistry}
69
69
  */
70
- declare function renderCanvasTree(components: CanvasComponentTree, registry: ComponentRegistry): React.ReactNode;
70
+ declare function renderCanvasTree(components: CanvasComponentTree, registry: ComponentRegistry): ReactNode;
71
71
  /**
72
72
  * Defines a component registry by dynamically importing each component's
73
73
  * JavaScript entry file from the discovery results.
@@ -0,0 +1,329 @@
1
+ import { GetOptions, JsonApiClient, JsonApiClientOptions, RawApiResponseWithData } from "@drupal-api-client/json-api-client";
2
+ //#region ../../node_modules/@drupal-api-client/api-client/dist/index.d.mts
3
+ /**
4
+ * The base URL for all API requests.
5
+ */
6
+ type BaseUrl = string;
7
+ /**
8
+ * The cache used by the ApiClient to store responses.
9
+ * @method get - gets a value from the cache
10
+ * @method set - sets a value in the cache
11
+ */
12
+ interface Cache {
13
+ get<T>(key: string, ...args: unknown[]): Promise<T>;
14
+ set<T>(key: string, value: T, ...args: unknown[]): Promise<unknown>;
15
+ }
16
+ //#endregion
17
+ //#region src/jsonapi-proxy.d.ts
18
+ /**
19
+ * @file
20
+ * Framework-agnostic URL mapping between a Drupal backend's JSON:API
21
+ * endpoints and a same-origin application proxy. The browser client maps
22
+ * upstream URLs to the proxy; the proxy (in the Canvas Headless SDK) validates
23
+ * and maps them back. Both sides share this module so they cannot disagree
24
+ * about which paths are supported.
25
+ *
26
+ * The supported endpoints are those the JSON:API client reaches:
27
+ * - the JSON:API prefix (resources, collections, views, the index), and
28
+ * - the Decoupled Router path translation endpoint (`getResourceByPath()`).
29
+ * Both may be preceded by one Drupal language path prefix.
30
+ *
31
+ * @see docs/adr/0021-code-component-runtime-compatibility-across-frontend-modes.md
32
+ */
33
+ /** The default JSON:API prefix of Drupal core's JSON:API module. */
34
+ declare const DEFAULT_JSONAPI_PREFIX = "jsonapi";
35
+ /** The default path of the Decoupled Router module's endpoint. */
36
+ declare const DEFAULT_ROUTER_PREFIX = "router/translate-path";
37
+ /**
38
+ * The response header the proxy sets on draft-session errors, and the value
39
+ * it carries when the session expired or is invalid.
40
+ */
41
+ declare const JSONAPI_PROXY_SESSION_HEADER = "X-Canvas-Draft-Session";
42
+ declare const JSONAPI_PROXY_SESSION_EXPIRED = "expired";
43
+ /** The `error` code of the proxy's draft-session error body. */
44
+ declare const JSONAPI_DRAFT_SESSION_EXPIRED_ERROR = "draft_session_expired";
45
+ /** The endpoints the proxy maps. */
46
+ interface JsonApiProxyEndpoints {
47
+ /** JSON:API prefix without surrounding slashes, e.g. `jsonapi`. */
48
+ apiPrefix: string;
49
+ /** Decoupled Router path without surrounding slashes. */
50
+ routerPrefix: string;
51
+ /**
52
+ * Absolute upstream JSON:API base URL when JSON:API is not served under the
53
+ * backend base URL and `apiPrefix` (for example on another host or path).
54
+ * Under the backend base URL it is a prefix override; elsewhere its site is
55
+ * `apiSiteUrl` (or, without one, its origin) and the rest its prefix. The
56
+ * supporting endpoints (path translation) stay under the backend base URL.
57
+ */
58
+ apiUrl?: string;
59
+ /**
60
+ * The site base URL (origin plus install path) of the site serving a
61
+ * foreign `apiUrl`, for example `https://api.example/mount` for
62
+ * `https://api.example/mount/api`: a locale prefix goes between it and the
63
+ * JSON:API prefix (`https://api.example/mount/fr/api`). Without it a foreign
64
+ * base accepts no locale prefix, since its site root is unknown.
65
+ */
66
+ apiSiteUrl?: string;
67
+ }
68
+ /** Where JSON:API requests go, resolved from the endpoint configuration. */
69
+ interface ResolvedJsonApiBase {
70
+ /**
71
+ * The absolute base URL (origin plus any site path) a locale prefix and
72
+ * the JSON:API prefix are appended to, without a trailing slash.
73
+ */
74
+ base: string;
75
+ /** The JSON:API prefix relative to `base`, without surrounding slashes. */
76
+ apiPrefix: string;
77
+ /** Whether JSON:API lives on another site than the backend base URL. */
78
+ foreign: boolean;
79
+ /**
80
+ * Whether `base` is a site root (so a locale path prefix can be applied):
81
+ * always for the backend site, for a foreign base only with `apiSiteUrl`.
82
+ */
83
+ siteKnown: boolean;
84
+ }
85
+ /**
86
+ * Resolves the JSON:API base and prefix. A full URL override under the
87
+ * backend base URL is a prefix override (a locale prefix goes between the
88
+ * site path and the prefix, as Drupal serves it); an override elsewhere is a
89
+ * foreign base whose path is the prefix.
90
+ */
91
+ declare function resolveJsonApiBase(baseUrl: string, endpoints?: Partial<JsonApiProxyEndpoints>): ResolvedJsonApiBase;
92
+ type JsonApiProxyEndpointName = 'jsonapi' | 'router';
93
+ /** A validated proxied path. */
94
+ interface ResolvedJsonApiProxyPath {
95
+ endpoint: JsonApiProxyEndpointName;
96
+ /** The site-relative upstream path, including any language prefix. */
97
+ path: string;
98
+ }
99
+ /** Strips surrounding slashes. */
100
+ declare function trimSlashes(value: string): string;
101
+ /**
102
+ * Whether `path` is a safe site-relative path: one leading slash, no empty,
103
+ * dot, or dot-dot segments, no backslashes, and no encoded slashes that could
104
+ * decode into a different path upstream.
105
+ */
106
+ declare function isSafeProxyPath(path: string): boolean;
107
+ /**
108
+ * Validates a site-relative path against the supported endpoints. Returns the
109
+ * endpoint it belongs to, or `null` when the path is unsafe or outside the
110
+ * boundary.
111
+ */
112
+ declare function resolveJsonApiProxyPath(path: string, endpoints?: Partial<JsonApiProxyEndpoints>): ResolvedJsonApiProxyPath | null;
113
+ /** Normalizes a backend base URL: absolute, no trailing slash. */
114
+ declare function normalizeBaseUrl(baseUrl: string): string;
115
+ /**
116
+ * Splits an absolute upstream URL into the part relative to the backend base
117
+ * URL. Returns `null` when the URL is not on the backend.
118
+ */
119
+ declare function toBackendRelativePath(url: string, baseUrl: string): {
120
+ path: string;
121
+ search: string;
122
+ } | null;
123
+ /**
124
+ * Maps an absolute upstream JSON:API URL to the same-origin proxy. Returns
125
+ * `null` for URLs that are not on the backend. Throws for backend URLs
126
+ * outside the supported endpoints, so an absolute Drupal URL can never bypass
127
+ * the proxy.
128
+ */
129
+ declare function mapJsonApiRequestToProxy(url: string, options: {
130
+ baseUrl: string;
131
+ proxyUrl: string;
132
+ } & Partial<JsonApiProxyEndpoints>): string | null;
133
+ /**
134
+ * Maps a proxied request path back to its absolute upstream URL. Returns
135
+ * `null` when the path is unsafe or outside the supported endpoints.
136
+ */
137
+ declare function mapProxyPathToUpstream(proxiedPath: string, options: {
138
+ baseUrl: string;
139
+ proxyUrl: string;
140
+ } & Partial<JsonApiProxyEndpoints>): {
141
+ url: string;
142
+ endpoint: JsonApiProxyEndpointName;
143
+ } | null;
144
+ //#endregion
145
+ //#region src/jsonapi-client.d.ts
146
+ type EndpointUrlSegments = Parameters<JsonApiClient['createURL']>[0];
147
+ /**
148
+ * Serializable JSON:API runtime configuration. Rendering integrations receive
149
+ * it from the environment (Drupal settings, Workbench, or the Headless SDK's
150
+ * server integration) and create the browser client from it. It carries no
151
+ * secrets.
152
+ */
153
+ interface JsonApiRuntimeConfig {
154
+ /** Absolute base URL of the Drupal backend, without a trailing slash. */
155
+ baseUrl: string;
156
+ /** JSON:API prefix without surrounding slashes. Default: `jsonapi`. */
157
+ apiPrefix?: string;
158
+ /**
159
+ * Absolute upstream JSON:API base URL when JSON:API is not served under
160
+ * `baseUrl`/`apiPrefix` (for example `https://api.example/drupal/jsonapi`).
161
+ * Takes precedence over `apiPrefix`: its path is the JSON:API prefix and its
162
+ * origin the JSON:API origin (a locale segment precedes the prefix). The
163
+ * Decoupled Router and other supporting endpoints stay under `baseUrl`.
164
+ */
165
+ apiUrl?: string;
166
+ /**
167
+ * The site base URL (origin plus install path) of the site serving a
168
+ * foreign `apiUrl`; a locale prefix goes between it and the JSON:API prefix.
169
+ * Without it a foreign `apiUrl` accepts no locale prefix.
170
+ */
171
+ apiSiteUrl?: string;
172
+ /** Decoupled Router path without surrounding slashes. */
173
+ routerPrefix?: string;
174
+ /**
175
+ * Same-origin proxy base URL (for example `/api/canvas/jsonapi`). When set,
176
+ * every backend request is sent through the proxy instead.
177
+ */
178
+ proxyUrl?: string;
179
+ /**
180
+ * JSON:API `resourceVersion` applied to reads (for example
181
+ * `rel:working-copy` in previews); `null` or omitted keeps default
182
+ * revisions.
183
+ */
184
+ resourceVersion?: string | null;
185
+ /** Whether the client serves an editor preview. */
186
+ preview?: boolean;
187
+ }
188
+ /** Full client configuration: runtime configuration plus runtime objects. */
189
+ interface JsonApiClientConfig extends JsonApiRuntimeConfig {
190
+ /** Authentication for direct backend requests (server side only). */
191
+ authentication?: JsonApiClientOptions['authentication'];
192
+ /**
193
+ * Response serializer. Defaults to `DefaultSerializer`; pass `null` to keep
194
+ * raw JSON:API documents.
195
+ */
196
+ serializer?: JsonApiClientOptions['serializer'] | null;
197
+ /**
198
+ * Client cache. Keys are scoped by resource version and `cacheScope`. A
199
+ * client that may carry a session — authenticated, sending cookies
200
+ * (`credentials` `same-origin`/`include`, or unspecified in a browser,
201
+ * where fetch sends same-origin cookies by default), going through the
202
+ * proxy, using a custom `fetch` transport, previewing, or reading a
203
+ * resource version — caches only with an explicit `cacheScope`: without
204
+ * one, responses fetched with one session could be served to another
205
+ * client sharing the cache, so the cache is ignored.
206
+ */
207
+ cache?: Cache;
208
+ /**
209
+ * Distinguishes cache entries of different sessions sharing one cache
210
+ * object. Defaults to `public` for clients that provably carry no session.
211
+ * Every other client must set a scope unique to the session (for example
212
+ * the session subject and token expiry), or `public` for a transport known
213
+ * to be anonymous, to cache at all.
214
+ */
215
+ cacheScope?: string;
216
+ /**
217
+ * Fetch implementation; defaults to the global `fetch`. A transport that
218
+ * attaches session credentials itself declares so with
219
+ * `fetchAuthenticates`, since the client cannot see what it sends.
220
+ */
221
+ fetch?: typeof fetch;
222
+ /**
223
+ * Whether the custom `fetch` transport authenticates requests with session
224
+ * credentials of its own. A 401 answered to such a request (unless the
225
+ * request opted out with `disableAuthentication`) is then a rejected
226
+ * session (`DraftSessionError`) rather than an ordinary failure.
227
+ */
228
+ fetchAuthenticates?: boolean;
229
+ /** Credentials mode for requests, e.g. `same-origin` for Drupal previews. */
230
+ credentials?: RequestCredentials;
231
+ /**
232
+ * Additional options passed to the upstream client (`indexLookup`,
233
+ * `defaultLocale`, `logger`, `debug`). Options this configuration already
234
+ * covers are ignored.
235
+ */
236
+ upstreamOptions?: Omit<JsonApiClientOptions, 'apiPrefix' | 'authentication' | 'cache' | 'customFetch' | 'decoupledRouterApiPrefix' | 'serializer'>;
237
+ }
238
+ /**
239
+ * Thrown when the draft preview session is rejected: the application proxy
240
+ * reports it expired or invalid, or Drupal answers an authenticated request
241
+ * with 401. Never swallowed by the client's fallbacks.
242
+ */
243
+ declare class DraftSessionError extends Error {
244
+ readonly status: number;
245
+ constructor(message: string, status?: number);
246
+ }
247
+ declare function isDraftSessionError(error: unknown): error is DraftSessionError;
248
+ /**
249
+ * The shared client implementation. Construct it with
250
+ * {@link createJsonApiClient}; the legacy `JsonApiClient` constructor extends
251
+ * it for Drupal and Workbench.
252
+ */
253
+ declare class CanvasJsonApiClient extends JsonApiClient {
254
+ /** The serializable part of the configuration. */
255
+ readonly runtimeConfig: JsonApiRuntimeConfig;
256
+ /** The resource version applied to reads, or `null`. */
257
+ readonly resourceVersion: string | null;
258
+ /** Where JSON:API requests go (base URL, prefix, foreign site or not). */
259
+ private readonly apiBase;
260
+ constructor(config: JsonApiClientConfig);
261
+ /**
262
+ * Obtaining or renewing the configured credentials is part of the session
263
+ * lifecycle: a failure there (for example an OAuth renewal answered with
264
+ * `invalid_grant`) is a rejected session, never an ordinary request error
265
+ * that a collection read could paper over with published items.
266
+ */
267
+ addAuthorizationHeader(options: RequestInit | undefined): Promise<RequestInit>;
268
+ /**
269
+ * Builds JSON:API URLs as Drupal serves them: the backend base URL
270
+ * including any site path, then a locale prefix, then the JSON:API prefix
271
+ * (the upstream builder resolves root-relative and would drop a site path
272
+ * such as `/sub`). A same-site full URL override is a prefix override; a
273
+ * foreign one has no known site root, so a locale prefix is refused.
274
+ */
275
+ createURL(segments: EndpointUrlSegments): Promise<string>;
276
+ /**
277
+ * Adds the configured resource version to a read unless the caller selected
278
+ * one explicitly.
279
+ */
280
+ private withResourceVersion;
281
+ getResource<T>(type: string, resourceId: string, options?: GetOptions): Promise<T | RawApiResponseWithData<T>>;
282
+ /**
283
+ * Collection reads at a resource version fetch each item's working copy in
284
+ * a separate request, because Drupal returns default revisions in
285
+ * collections. Working copies are merged into the raw document before the
286
+ * serializer runs. A failing ordinary item fetch keeps the original item;
287
+ * draft-session errors propagate. Raw responses bypass this.
288
+ *
289
+ * An omitted or false rawResponse returns the deserialized T. A literal
290
+ * true returns the response wrapper; a dynamic flag retains both types.
291
+ */
292
+ getCollection<T>(type: string, options: GetOptions & {
293
+ rawResponse: true;
294
+ }): Promise<RawApiResponseWithData<T>>;
295
+ getCollection<T>(type: string, options?: GetOptions & {
296
+ rawResponse?: false;
297
+ }): Promise<T>;
298
+ getCollection<T>(type: string, options?: GetOptions): Promise<T | RawApiResponseWithData<T>>;
299
+ /**
300
+ * Replaces each collection item with its working copy. Item reads keep the
301
+ * read options that apply to a single resource — the locale, sparse
302
+ * fieldsets, includes, and a resource version the caller selected
303
+ * explicitly — but not collection-only parameters (filter, sort, page).
304
+ * Included resources returned with the working copies replace the
305
+ * collection's included resources of the same identity, so relationships
306
+ * of a working copy resolve against the document.
307
+ */
308
+ private hydrateWorkingCopies;
309
+ }
310
+ /**
311
+ * Creates the shared JSON:API client from explicit configuration. This is the
312
+ * construction path for rendering integrations and the Headless SDK; it has
313
+ * no environment guard.
314
+ */
315
+ declare function createJsonApiClient(config: JsonApiClientConfig): CanvasJsonApiClient;
316
+ /**
317
+ * The legacy JSON:API client for Drupal-rendered Code Components and
318
+ * Workbench: configured from `drupalSettings`, with `DefaultSerializer` and
319
+ * the site's JSON:API prefix. Outside those environments it throws an
320
+ * actionable migration error, even when a base URL is supplied.
321
+ *
322
+ * @deprecated Use `useJsonApiClient()` in React Code Components, or the
323
+ * Headless SDK's `getClient()` in headless server code.
324
+ */
325
+ declare class LegacyJsonApiClient extends CanvasJsonApiClient {
326
+ constructor(baseUrl?: BaseUrl, options?: JsonApiClientOptions);
327
+ }
328
+ //#endregion
329
+ export { trimSlashes as C, toBackendRelativePath as S, mapJsonApiRequestToProxy as _, LegacyJsonApiClient as a, resolveJsonApiBase as b, DEFAULT_JSONAPI_PREFIX as c, JSONAPI_PROXY_SESSION_EXPIRED as d, JSONAPI_PROXY_SESSION_HEADER as f, isSafeProxyPath as g, ResolvedJsonApiProxyPath as h, JsonApiRuntimeConfig as i, DEFAULT_ROUTER_PREFIX as l, JsonApiProxyEndpoints as m, DraftSessionError as n, createJsonApiClient as o, JsonApiProxyEndpointName as p, JsonApiClientConfig as r, isDraftSessionError as s, CanvasJsonApiClient as t, JSONAPI_DRAFT_SESSION_EXPIRED_ERROR as u, mapProxyPathToUpstream as v, resolveJsonApiProxyPath as x, normalizeBaseUrl as y };