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/README.md +177 -45
- package/dist/context-Cb4HbPbR.d.ts +32 -0
- package/dist/drupal-utils-CUaK4jOk.d.ts +117 -0
- package/dist/drupal-utils.d.ts +2 -79
- package/dist/drupal-utils.js +23 -0
- package/dist/index.d.ts +113 -3
- package/dist/index.js +78 -2
- package/dist/json-render-utils.d.ts +3 -3
- package/dist/jsonapi-client-BAQ3V5CC.d.ts +329 -0
- package/dist/jsonapi-client-CejP62bM.js +539 -0
- package/dist/jsonapi-client.d.ts +2 -2
- package/dist/jsonapi-client.js +2 -17
- package/dist/migration-CPBzW78_.js +63 -0
- package/dist/react.d.ts +25 -0
- package/dist/react.js +158 -0
- package/package.json +11 -1
- package/dist/jsonapi-client-Q84JvzCD.d.ts +0 -13
package/dist/index.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import FormattedText from "./FormattedText.js";
|
|
2
|
-
import {
|
|
3
|
-
import
|
|
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
|
-
|
|
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 {
|
|
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,
|
|
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):
|
|
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):
|
|
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 };
|