@jsondrop/core 0.0.0-stage → 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Valentino Međimorec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,127 @@
-# Temporary Holding Version
+# @jsondrop/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A typed, framework-agnostic client for Drupal's JSON:API. No dependencies.
+
+```sh
+npm install @jsondrop/core
+```
+
+## Usage
+
+```ts
+import { JsonApiClient, clientCredentials } from '@jsondrop/core';
+
+const drupal = new JsonApiClient({
+  baseUrl: 'https://cms.example.com',
+  auth: clientCredentials({ clientId: '…', clientSecret: '…', scope: 'content:read' }),
+});
+
+const articles = await drupal.getCollection('node--article', {
+  query: {
+    include: ['field_image', 'uid'],
+    filter: { status: 1 },
+    sort: ['-created'],
+    page: { limit: 10 },
+  },
+});
+
+articles[0].field_image; // the included file--file, with relationshipMeta.alt
+```
+
+Responses are deserialized: attributes and relationships sit on one
+object, and relationships are replaced by their included resources
+(recursively). A relationship whose target was not included is a stub
+(`{ id, type, stub: true }`, see `isStub`).
+
+## Typing your resources
+
+Register resource types once, by declaration merging:
+
+```ts
+import type { ResourceBase, ToOne, ToMany } from '@jsondrop/core';
+
+interface NodeArticle extends ResourceBase<'node--article'> {
+  title: string;
+  body: { value: string; processed: string } | null;
+  field_tags: ToMany<TaxonomyTerm>;
+  field_image: ToOne<File>;
+}
+
+declare module '@jsondrop/core' {
+  interface ResourceTypes {
+    'node--article': NodeArticle;
+  }
+}
+
+const article = await drupal.getResource('node--article', id); // NodeArticle
+```
+
+## API
+
+**Resources**: `getResource`, `getCollection`, `getPage` (with `next()`),
+`iterate` (async, follows `next` links), `createResource`, `updateResource`,
+`deleteResource`, `uploadFile`.
+
+**Requests** relative to the API prefix, for custom resources:
+`get`, `post`, `patch`, `delete`, `request`. They return the raw document
+alongside `data`, `meta`, `links`, `status` and `headers`.
+
+**Options** (client, some per request):
+
+| Option | |
+|---|---|
+| `baseUrl` | Site origin |
+| `apiPrefix` | Default `/jsonapi` |
+| `locale`, `defaultLocale` | Language path prefix (`/de/jsonapi/…`) |
+| `auth` | `bearer`, `basic`, `sessionCookie`, `clientCredentials`, or your own `AuthStrategy`; `false` per request |
+| `headers` | Object or (async) function |
+| `resourcePaths` | Type → path, for types renamed with JSON:API Extras |
+| `fetchOptions` | Passed to `fetch`, e.g. `{ next: { revalidate: 60, tags: ['node:1'] } }` |
+| `onResponse` | Called after each request, for logging |
+
+## Users logging in (OAuth)
+
+`OAuthClient` runs simple_oauth 6.x's authorization code flow with PKCE
+and refresh tokens (6.x dropped the password and implicit grants):
+
+```ts
+import { OAuthClient } from '@jsondrop/core';
+
+const oauth = new OAuthClient({ baseUrl, clientId, clientSecret, redirectUri, scope: 'openid profile' });
+
+// 1. Redirect to Drupal; keep state + codeVerifier in an httpOnly cookie.
+const { url, state, codeVerifier } = await oauth.startLogin();
+// 2. On the redirect back: checks the state, exchanges the code.
+const tokens = await oauth.finishLogin({ code, state: returnedState }, { state, codeVerifier });
+// 3. Store the tokens server-side; requests as the user:
+const asUser = drupal.extend({ auth: oauth.strategy(tokenStore) });
+```
+
+The strategy refreshes the token before it expires and after a 401.
+Refresh tokens are single-use, so concurrent refreshes share one request:
+keep one `OAuthClient` per app. When Drupal rejects the refresh token, the
+store is emptied and requests throw `LoginRequiredError`: send the user to
+log in again. `oauth.userInfo(accessToken)` reads OpenID Connect claims.
+See [example 7](../../examples/07-user-login.ts).
+
+**Renamed resources** (JSON:API Extras): the API's entry point lists every
+type's path, so let the client read them once at startup instead of
+mapping them by hand:
+
+```ts
+const drupal = await new JsonApiClient({ baseUrl }).withDiscoveredPaths();
+drupal.resourcePath('products'); // '/products', as the site configures it
+```
+
+`client.extend({ headers })` derives a client that adds headers (a cart
+token, a market) and shares the parent's auth and token cache.
+
+**Errors**: non-2xx responses throw `JsonApiError` with `status`, `errors`
+and the document; its `message` is Drupal's `detail`. On a 401, strategies
+with cached tokens are renewed and the request retried once.
+
+**Links**: absolute URLs from documents (`links.next`) are sent to
+`baseUrl`'s origin, so a Drupal behind a proxy that builds links with an
+internal host still works, and credentials never go elsewhere.
+
+**Queries** also accept a prebuilt string, e.g. from drupal-jsonapi-params.

package/dist/auth.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Authentication strategies. A strategy returns the headers that
+ * authenticate one request; the client calls it before every request.
+ *
+ * A strategy may also implement `invalidate()`. When a request comes back
+ * 401, the client calls it and retries once, so cached tokens that Drupal
+ * has revoked are replaced transparently.
+ */
+export interface AuthContext {
+    /** Site origin the client talks to, without a trailing slash. */
+    baseUrl: string;
+    fetch: typeof fetch;
+}
+export interface AuthStrategy {
+    headers(context: AuthContext): HeadersInit | undefined | Promise<HeadersInit | undefined>;
+    /**
+     * Called after a 401: drop cached credentials, so the retry gets fresh
+     * ones. Return `false` when there is nothing to renew, to skip the retry.
+     */
+    invalidate?(): void | boolean;
+}
+type Value = string | null | undefined;
+type ValueSource = Value | (() => Value | Promise<Value>);
+/** `Authorization: Bearer <token>`, from a token or a function that returns one. */
+export declare function bearer(token: ValueSource): AuthStrategy;
+/** HTTP Basic authentication (Drupal core's `basic_auth` module). */
+export declare function basic(username: string, password: string): AuthStrategy;
+/**
+ * Forwards a Drupal session cookie (`SSESS…=value`), e.g. one a server-side
+ * login obtained and the application keeps in its own httpOnly cookie.
+ */
+export declare function sessionCookie(cookie: ValueSource): AuthStrategy;
+export interface ClientCredentialsOptions {
+    clientId: string;
+    clientSecret: string;
+    /** Space-separated scopes. */
+    scope?: string;
+    /** Token endpoint path or absolute URL. Default `/oauth/token` (simple_oauth). */
+    tokenUrl?: string;
+    /** Renew this many milliseconds before expiry. Default 30 seconds. */
+    renewBeforeMs?: number;
+}
+export interface TokenResponse {
+    access_token: string;
+    token_type?: string;
+    expires_in?: number;
+    refresh_token?: string;
+    scope?: string;
+    /** With the `openid` scope (simple_oauth's OpenID Connect). */
+    id_token?: string;
+}
+export declare class OAuthError extends Error {
+    readonly status: number;
+    readonly body: string;
+    readonly name = "OAuthError";
+    /** The OAuth error code, e.g. `invalid_grant` (expired or reused refresh token), `invalid_client`. */
+    readonly error: string | null;
+    constructor(status: number, body: string);
+}
+/** POSTs a token request (form-encoded) and returns the token response. */
+export declare function requestToken(context: AuthContext, tokenUrl: string, params: Record<string, string | undefined>): Promise<TokenResponse>;
+/** An absolute URL for a site path, or the URL itself. */
+export declare function absolute(baseUrl: string, pathOrUrl: string): string;
+/**
+ * OAuth 2 client credentials (simple_oauth), for server-to-server requests.
+ * The token is cached in this strategy until shortly before it expires, and
+ * concurrent requests share one token request. Never use it in a browser:
+ * it needs the client secret.
+ */
+export declare function clientCredentials(options: ClientCredentialsOptions): AuthStrategy & {
+    token(context: AuthContext): Promise<string>;
+};
+export {};
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,WAAW;IAC1B,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,KAAK,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,WAAW,GAAG,SAAS,GAAG,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAAC;IAC1F;;;OAGG;IACH,UAAU,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC;CAC/B;AAED,KAAK,KAAK,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;AACvC,KAAK,WAAW,GAAG,KAAK,GAAG,CAAC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;AAM1D,oFAAoF;AACpF,wBAAgB,MAAM,CAAC,KAAK,EAAE,WAAW,GAAG,YAAY,CAOvD;AAED,qEAAqE;AACrE,wBAAgB,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,CAItE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,CAO/D;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kFAAkF;IAClF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,qBAAa,UAAW,SAAQ,KAAK;IAKvB,QAAQ,CAAC,MAAM,EAAE,MAAM;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM;IAJ1D,SAAkB,IAAI,gBAAgB;IACtC,sGAAsG;IACtG,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;gBAET,MAAM,EAAE,MAAM,EAAW,IAAI,EAAE,MAAM;CAY3D;AAED,2EAA2E;AAC3E,wBAAsB,YAAY,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC,CAc7I;AAED,0DAA0D;AAC1D,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,wBAAwB,GAAG,YAAY,GAAG;IAAE,KAAK,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;CAAE,CAqCpI"}

package/dist/auth.js

@@ -0,0 +1,123 @@
+/**
+ * Authentication strategies. A strategy returns the headers that
+ * authenticate one request; the client calls it before every request.
+ *
+ * A strategy may also implement `invalidate()`. When a request comes back
+ * 401, the client calls it and retries once, so cached tokens that Drupal
+ * has revoked are replaced transparently.
+ */
+async function value(source) {
+    return typeof source === 'function' ? source() : source;
+}
+/** `Authorization: Bearer <token>`, from a token or a function that returns one. */
+export function bearer(token) {
+    return {
+        async headers() {
+            const resolved = await value(token);
+            return resolved ? { Authorization: `Bearer ${resolved}` } : undefined;
+        },
+    };
+}
+/** HTTP Basic authentication (Drupal core's `basic_auth` module). */
+export function basic(username, password) {
+    const bytes = new TextEncoder().encode(`${username}:${password}`);
+    const encoded = btoa(String.fromCharCode(...bytes));
+    return { headers: () => ({ Authorization: `Basic ${encoded}` }) };
+}
+/**
+ * Forwards a Drupal session cookie (`SSESS…=value`), e.g. one a server-side
+ * login obtained and the application keeps in its own httpOnly cookie.
+ */
+export function sessionCookie(cookie) {
+    return {
+        async headers() {
+            const resolved = await value(cookie);
+            return resolved ? { Cookie: resolved } : undefined;
+        },
+    };
+}
+export class OAuthError extends Error {
+    status;
+    body;
+    name = 'OAuthError';
+    /** The OAuth error code, e.g. `invalid_grant` (expired or reused refresh token), `invalid_client`. */
+    error;
+    constructor(status, body) {
+        super(`OAuth token request failed: HTTP ${status}${body ? ` ${body}` : ''}`);
+        this.status = status;
+        this.body = body;
+        let error = null;
+        try {
+            const parsed = JSON.parse(body);
+            error = typeof parsed.error === 'string' ? parsed.error : null;
+        }
+        catch {
+            // Not JSON.
+        }
+        this.error = error;
+    }
+}
+/** POSTs a token request (form-encoded) and returns the token response. */
+export async function requestToken(context, tokenUrl, params) {
+    const body = new URLSearchParams();
+    for (const [name, value] of Object.entries(params)) {
+        if (value !== undefined && value !== '')
+            body.set(name, value);
+    }
+    const response = await context.fetch(absolute(context.baseUrl, tokenUrl), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+        body,
+    });
+    if (!response.ok) {
+        throw new OAuthError(response.status, await response.text());
+    }
+    return (await response.json());
+}
+/** An absolute URL for a site path, or the URL itself. */
+export function absolute(baseUrl, pathOrUrl) {
+    return /^https?:\/\//.test(pathOrUrl) ? pathOrUrl : `${baseUrl}${pathOrUrl}`;
+}
+/**
+ * OAuth 2 client credentials (simple_oauth), for server-to-server requests.
+ * The token is cached in this strategy until shortly before it expires, and
+ * concurrent requests share one token request. Never use it in a browser:
+ * it needs the client secret.
+ */
+export function clientCredentials(options) {
+    const renewBeforeMs = options.renewBeforeMs ?? 30_000;
+    let cached = null;
+    let pending = null;
+    const request = async (context) => {
+        const token = await requestToken(context, options.tokenUrl ?? '/oauth/token', {
+            grant_type: 'client_credentials',
+            client_id: options.clientId,
+            client_secret: options.clientSecret,
+            scope: options.scope,
+        });
+        cached = {
+            token: token.access_token,
+            expiresAt: token.expires_in === undefined ? Number.POSITIVE_INFINITY : Date.now() + token.expires_in * 1000,
+        };
+        return cached.token;
+    };
+    const strategy = {
+        async token(context) {
+            if (cached && cached.expiresAt - renewBeforeMs > Date.now()) {
+                return cached.token;
+            }
+            pending ??= request(context).finally(() => {
+                pending = null;
+            });
+            return pending;
+        },
+        async headers(context) {
+            return { Authorization: `Bearer ${await strategy.token(context)}` };
+        },
+        invalidate() {
+            cached = null;
+        },
+    };
+    return strategy;
+}
+//# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAoBH,KAAK,UAAU,KAAK,CAAC,MAAmB;IACtC,OAAO,OAAO,MAAM,KAAK,UAAU,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;AAC1D,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,MAAM,CAAC,KAAkB;IACvC,OAAO;QACL,KAAK,CAAC,OAAO;YACX,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,CAAC;YACpC,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,QAAQ,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QACxE,CAAC;KACF,CAAC;AACJ,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,KAAK,CAAC,QAAgB,EAAE,QAAgB;IACtD,MAAM,KAAK,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,GAAG,QAAQ,IAAI,QAAQ,EAAE,CAAC,CAAC;IAClE,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;IACpD,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,aAAa,EAAE,SAAS,OAAO,EAAE,EAAE,CAAC,EAAE,CAAC;AACpE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,MAAmB;IAC/C,OAAO;QACL,KAAK,CAAC,OAAO;YACX,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,CAAC;YACrC,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;QACrD,CAAC;KACF,CAAC;AACJ,CAAC;AAuBD,MAAM,OAAO,UAAW,SAAQ,KAAK;IAKd;IAAyB;IAJ5B,IAAI,GAAG,YAAY,CAAC;IACtC,sGAAsG;IAC7F,KAAK,CAAgB;IAE9B,YAAqB,MAAc,EAAW,IAAY;QACxD,KAAK,CAAC,oCAAoC,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAD1D,WAAM,GAAN,MAAM,CAAQ;QAAW,SAAI,GAAJ,IAAI,CAAQ;QAExD,IAAI,KAAK,GAAkB,IAAI,CAAC;QAChC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAwB,CAAC;YACvD,KAAK,GAAG,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;QACjE,CAAC;QACD,MAAM,CAAC;YACL,YAAY;QACd,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF;AAED,2EAA2E;AAC3E,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,OAAoB,EAAE,QAAgB,EAAE,MAA0C;IACnH,MAAM,IAAI,GAAG,IAAI,eAAe,EAAE,CAAC;IACnC,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnD,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,EAAE;YAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACjE,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,EAAE;QACxE,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,mCAAmC,EAAE,MAAM,EAAE,kBAAkB,EAAE;QAC5F,IAAI;KACL,CAAC,CAAC;IACH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;QACjB,MAAM,IAAI,UAAU,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/D,CAAC;IACD,OAAO,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAkB,CAAC;AAClD,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,QAAQ,CAAC,OAAe,EAAE,SAAiB;IACzD,OAAO,cAAc,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,OAAO,GAAG,SAAS,EAAE,CAAC;AAC/E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAiC;IACjE,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,MAAM,CAAC;IACtD,IAAI,MAAM,GAAgD,IAAI,CAAC;IAC/D,IAAI,OAAO,GAA2B,IAAI,CAAC;IAE3C,MAAM,OAAO,GAAG,KAAK,EAAE,OAAoB,EAAmB,EAAE;QAC9D,MAAM,KAAK,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,IAAI,cAAc,EAAE;YAC5E,UAAU,EAAE,oBAAoB;YAChC,SAAS,EAAE,OAAO,CAAC,QAAQ;YAC3B,aAAa,EAAE,OAAO,CAAC,YAAY;YACnC,KAAK,EAAE,OAAO,CAAC,KAAK;SACrB,CAAC,CAAC;QACH,MAAM,GAAG;YACP,KAAK,EAAE,KAAK,CAAC,YAAY;YACzB,SAAS,EAAE,KAAK,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,UAAU,GAAG,IAAI;SAC5G,CAAC;QACF,OAAO,MAAM,CAAC,KAAK,CAAC;IACtB,CAAC,CAAC;IAEF,MAAM,QAAQ,GAAG;QACf,KAAK,CAAC,KAAK,CAAC,OAAoB;YAC9B,IAAI,MAAM,IAAI,MAAM,CAAC,SAAS,GAAG,aAAa,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;gBAC5D,OAAO,MAAM,CAAC,KAAK,CAAC;YACtB,CAAC;YACD,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE;gBACxC,OAAO,GAAG,IAAI,CAAC;YACjB,CAAC,CAAC,CAAC;YACH,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,KAAK,CAAC,OAAO,CAAC,OAAoB;YAChC,OAAO,EAAE,aAAa,EAAE,UAAU,MAAM,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;QACtE,CAAC;QACD,UAAU;YACR,MAAM,GAAG,IAAI,CAAC;QAChB,CAAC;KACF,CAAC;IACF,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/client.d.ts

@@ -0,0 +1,175 @@
+import type { AuthStrategy } from './auth.js';
+import { type QueryInput } from './query.js';
+import { type ResourceInput } from './serialize.js';
+import type { Document, Links, Meta, Resource, ResourceOf, ResourceType } from './types.js';
+export declare const JSON_API_MEDIA_TYPE = "application/vnd.api+json";
+/**
+ * Extra `fetch` options: `cache`, `credentials`, and framework extensions
+ * such as Next.js's `next: { revalidate, tags }`.
+ */
+export type FetchOptions = Omit<RequestInit, 'method' | 'headers' | 'body' | 'signal'> & Record<string, unknown>;
+type HeadersSource = HeadersInit | (() => HeadersInit | undefined | Promise<HeadersInit | undefined>);
+/** One finished request, for logging or a request inspector. */
+export interface RequestRecord {
+    method: string;
+    url: string;
+    status: number;
+    durationMs: number;
+    requestBody?: unknown;
+    responseBody?: unknown;
+}
+export interface JsonApiClientOptions {
+    /** Site origin, e.g. `https://example.com`. A trailing slash is ignored. */
+    baseUrl: string;
+    /** Path prefix of the JSON:API. Default `/jsonapi`. */
+    apiPrefix?: string;
+    /** Language of requests; sent as a path prefix unless it is `defaultLocale`. */
+    locale?: string;
+    /** The site's default language, which has no path prefix. */
+    defaultLocale?: string;
+    auth?: AuthStrategy;
+    /** Headers added to every request. */
+    headers?: HeadersSource;
+    /**
+     * JSON:API path per resource type, relative to `apiPrefix`, for types
+     * whose path is not the default `/{entity_type}/{bundle}` (renamed with
+     * JSON:API Extras, or custom resources).
+     */
+    resourcePaths?: Record<string, string>;
+    /**
+     * Computes paths for whole families of types (commerce_api's renamed
+     * Commerce types); `undefined` falls through to the default. Consulted
+     * after `resourcePaths`.
+     */
+    resolveResourcePath?: (type: string) => string | undefined;
+    /** Default `fetch` options for every request. */
+    fetchOptions?: FetchOptions;
+    fetch?: typeof fetch;
+    /** Called after every request, failed ones included. */
+    onResponse?: (record: RequestRecord) => void;
+}
+export interface RequestOptions {
+    query?: QueryInput;
+    /** A JSON:API document, sent as JSON. */
+    body?: unknown;
+    /** A raw body (file uploads); the caller sets its Content-Type. */
+    rawBody?: BodyInit;
+    headers?: HeadersInit;
+    /** Language of this request, overriding the client's. */
+    locale?: string;
+    /** `false` sends this request anonymously. */
+    auth?: AuthStrategy | false;
+    fetchOptions?: FetchOptions;
+    signal?: AbortSignal;
+}
+/** Options for the resource-level methods. */
+export type ResourceRequestOptions = Omit<RequestOptions, 'body' | 'rawBody'>;
+/** A response: the raw document plus its deserialized primary data. */
+export interface JsonApiResponse<T> {
+    status: number;
+    headers: Headers;
+    document: Document;
+    data: T;
+    meta: Meta;
+    links: Links;
+}
+/** One page of a collection. */
+export interface Page<T> {
+    data: T[];
+    meta: Meta;
+    links: Links;
+    document: Document;
+    hasNext: boolean;
+    /** The following page, or NULL on the last one. */
+    next(): Promise<Page<T> | null>;
+}
+export interface FileInput {
+    data: Blob | ArrayBuffer | Uint8Array;
+    filename: string;
+}
+/**
+ * A client for Drupal's JSON:API.
+ *
+ * Two levels:
+ * - resource methods (`getResource`, `getCollection`, `createResource`, …)
+ *   take a resource type name and return deserialized resources, typed by
+ *   the {@link ResourceTypes} registry;
+ * - request methods (`get`, `post`, `request`, …) take a path relative to
+ *   the API prefix, for custom resources such as commerce_api's cart.
+ *
+ * Non-2xx responses throw {@link JsonApiError}.
+ */
+export declare class JsonApiClient {
+    readonly options: JsonApiClientOptions;
+    readonly baseUrl: string;
+    readonly apiPrefix: string;
+    private readonly fetchImpl;
+    constructor(options: JsonApiClientOptions);
+    /**
+     * A client with some options replaced. Headers are combined: the new
+     * ones are added after (and win over) this client's. The auth strategy is
+     * shared unless replaced, so a cached token is reused.
+     */
+    extend(options: Partial<JsonApiClientOptions>): JsonApiClient;
+    /**
+     * Reads every resource type's path from the API's entry point (`GET
+     * /jsonapi`), which lists them as links keyed by type name. Covers types
+     * renamed or moved with JSON:API Extras without mapping them by hand.
+     *
+     * ```ts
+     * const drupal = await new JsonApiClient({ baseUrl }).withDiscoveredPaths();
+     * ```
+     */
+    discoverResourcePaths(options?: Pick<RequestOptions, 'auth' | 'headers' | 'fetchOptions' | 'signal'>): Promise<Record<string, string>>;
+    /**
+     * A client with the paths from {@link discoverResourcePaths}. Paths
+     * configured in `resourcePaths` keep precedence. Discover once at
+     * startup and reuse the client: it is one request.
+     */
+    withDiscoveredPaths(options?: Parameters<JsonApiClient['discoverResourcePaths']>[0]): Promise<JsonApiClient>;
+    /** JSON:API path of a resource type, relative to the API prefix. */
+    resourcePath(type: string): string;
+    /** Absolute URL of an API path. */
+    url(path: string, query?: QueryInput, locale?: string): string;
+    /**
+     * Absolute URL of a site path outside the API (`/router/translate-path`),
+     * with the language prefix.
+     */
+    siteUrl(path: string, query?: QueryInput, locale?: string): string;
+    getResource<T extends ResourceType>(type: T, id: string, options?: ResourceRequestOptions): Promise<ResourceOf<T>>;
+    /** One page of a collection (Drupal's default page size is 50). */
+    getCollection<T extends ResourceType>(type: T, options?: ResourceRequestOptions): Promise<ResourceOf<T>[]>;
+    /** A page of a collection, with its meta and a way to the next page. */
+    getPage<T extends ResourceType>(type: T, options?: ResourceRequestOptions): Promise<Page<ResourceOf<T>>>;
+    /** Every resource of a collection, following `next` links page by page. */
+    iterate<T extends ResourceType>(type: T, options?: ResourceRequestOptions): AsyncGenerator<ResourceOf<T>, void, undefined>;
+    createResource<T extends ResourceType>(type: T, input: ResourceInput, options?: ResourceRequestOptions): Promise<ResourceOf<T>>;
+    updateResource<T extends ResourceType>(type: T, id: string, input: Omit<ResourceInput, 'id'>, options?: ResourceRequestOptions): Promise<ResourceOf<T>>;
+    deleteResource(type: ResourceType, id: string, options?: ResourceRequestOptions): Promise<void>;
+    /**
+     * Uploads a file into a file field (core's JSON:API file upload). With
+     * `entityId`, the file is attached to that entity's field; without, a
+     * temporary file is created to reference in a later create or update.
+     */
+    uploadFile(type: ResourceType, field: string, file: FileInput, options?: ResourceRequestOptions & {
+        entityId?: string;
+    }): Promise<ResourceOf<'file--file'>>;
+    get<T = Resource | Resource[] | null>(path: string, options?: Omit<RequestOptions, 'body' | 'rawBody'>): Promise<JsonApiResponse<T>>;
+    post<T = Resource | Resource[] | null>(path: string, body?: unknown, options?: Omit<RequestOptions, 'body'>): Promise<JsonApiResponse<T>>;
+    patch<T = Resource | Resource[] | null>(path: string, body?: unknown, options?: Omit<RequestOptions, 'body'>): Promise<JsonApiResponse<T>>;
+    delete<T = Resource | Resource[] | null>(path: string, body?: unknown, options?: Omit<RequestOptions, 'body'>): Promise<JsonApiResponse<T>>;
+    /**
+     * Sends a request. `path` is relative to the API prefix, or an absolute
+     * URL (from a document's links, or {@link siteUrl}); an absolute URL keeps
+     * only its path and query, plus `query` if given, and is sent to
+     * `baseUrl`, so links Drupal builds with an internal host (behind a
+     * proxy) still work and credentials never leave the site.
+     */
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<JsonApiResponse<T>>;
+    private send;
+    private parse;
+    private page;
+    private sameOrigin;
+}
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}