Add PloneClient.extend() and clientEndpoints utility for custom endpoints

[sneridagh]

Summary

Add-ons had no clean way to add methods for their own REST API endpoints to the Plone client. This PR adds one, in two layers:

@plone/client (framework-agnostic)

• PloneClient.extend(methods) returns a subclass with the given methods. It can be chained, leaves the original class unchanged, and gives the added methods their types without augmentation.
• Extensions are assigned in the constructor rather than on the prototype, because the core endpoints are instance fields. This lets an extension override a core method such as getContent.
• initialize() now returns an instance of the class it's called on, so subclasses and extended classes work.
• New PloneClientExtensions interface, merged into PloneClient. Add-ons augment it so that every value typed PloneClient (for example ploneClientContext) knows about their methods.
• New exports: apiRequest, getBackendURL, and the types ApiRequestParams, PloneClientConfig, RequestResponse, RequestError, PloneClientMethods and ExtendedPloneClient. Custom endpoints are written the same way as core ones.
• Removed the nonexistent src/bla.ts entry from the tsup config.

Aurora

• New clientEndpoints utility type. The new getPloneClientClass() in the middleware combines the ploneClient utility with every registered clientEndpoints set. Add-ons register their own endpoints declaratively, with no dependency on load order and without overwriting each other.

config.registerUtility({
  type: 'clientEndpoints',
  name: 'my-addon',
  method: () => ({ getIdentityProviders }),
});

declare module '@plone/client' {
  interface PloneClientExtensions {
    getIdentityProviders: typeof getIdentityProviders;
  }
}

Docs: new how-to guide docs/how-to-guides/add-client-endpoints.md, plus a section in the client README.

Tests

• packages/client/src/client.test.ts: unit tests with axios mocked, no backend needed. They cover polymorphic initialize, this binding, chaining, overrides, the original class staying unchanged, and method binding (see below).
• apps/aurora/app/middleware.server.test.ts: tests for getPloneClientClass(), including extending a custom ploneClient class.
• I verified consumer typing by compiling a temporary file in apps/aurora against the built package. Augmented methods show up on LoaderUtilityArgs['cli'], and calling an unknown method is a type error.

Fix: endpoint methods were never bound to the instance

The bug

The PloneClient constructor was meant to bind every endpoint method to its instance:

Object.values(this).forEach((propertyValue) => {
  if (propertyValue instanceof Function) {
    propertyValue = propertyValue.bind(this);
  }
});

Function.prototype.bind() does not change the function it's called on. It returns a new function. Here that new function was assigned to propertyValue, which is only the callback's parameter, and it was thrown away when the callback returned. Nothing was written back to the instance, so the loop ran once per endpoint and had no effect.

Impact

Endpoints get the client as this only when called as cli.method(). Every endpoint starts by reading this.config, so any call that detaches the method from the client fails:

const { getContent } = cli;
await getContent({ path: '/' });
// TypeError: Cannot read properties of undefined (reading 'config')

paths.map(cli.getContent);       // same failure
someLib.onLoad(cli.getSite);     // same failure

In a detached call this is undefined, because ES modules run in strict mode.

Why it went unnoticed

Every endpoint is declared with this: PloneClient, so TypeScript rejects detached calls at compile time ("The 'this' context of type 'void' is not assignable to method's 'this' of type 'PloneClient'"). All code in the monorepo calls cli.x(). The bug affects plain JavaScript consumers, code that casts with as any, and libraries that take callbacks.

Interaction with extend()

extend() assigns its methods in the subclass constructor, which runs after the base constructor. Fixing only the base loop would bind the core endpoints but leave every extension method unbound.

The fix

A small bindMethods(target, methods) helper assigns each function to the instance, bound to it. Both places use it:

• the base constructor calls bindMethods(this, this). The core endpoints are class fields, so they're already on the instance when the constructor body runs.
• the extend() subclass constructor calls bindMethods(this, extensions) instead of Object.assign.

Each instance gets its own bound copies. A method taken from one client always uses that client's config, including its token, which matters because Aurora creates one client per request.

Trade-off: a bound method can no longer be pointed at a different this with .call() or .apply(). Nothing relies on that.

Not changed: types

The public types are unchanged. TypeScript still types endpoints with this: PloneClient and still flags detached calls, even though they now work at runtime. Allowing them in the types would mean re-declaring every core field as OmitThisParameter<…>, which can be a follow-up if we want it. The new tests use an explicit OmitThisParameter cast to call methods detached.

Tests

New PloneClient method binding tests in client.test.ts cover a detached core method, a detached extension method, and per-instance binding (two instances with different apiPath). On the old constructor all three fail; with the fix all pass.

Side note: packages/client/tsconfig.json excludes src/**/*.test.{ts,tsx}, but tsc doesn't support brace patterns, so test files are in fact type-checked by check:ts.