drupal-canvas 0.5.2 → 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 +209 -3
- package/dist/index.js +220 -2
- package/dist/json-render-utils.d.ts +3 -3
- package/dist/json-render-utils.js +11 -1
- 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
|
@@ -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 };
|