@supersoniks/concorde 4.9.9 → 4.9.92

package/src/decorators.ts

@@ -19,6 +19,8 @@ export const get = api.get;
 export const post = api.post;
 export const put = api.put;
 export const patch = api.patch;
+export const refetch = api.refetch;
+export const send = api.send;
 export {
   DataProviderKey,
   type DataProviderKeyHost,
@@ -27,6 +29,9 @@ export { Endpoint };
 export type { ApiResult, ApiGetResult } from "./core/utils/api";
 export type {
   ApiSendOptions,
+  ApiSendDecoratorHandle,
+  ApiMethodActionOptions,
+  GetDecoratorHandle,
   GetOptions,
   PostOptions,
   PutOptions,
@@ -57,4 +62,6 @@ window["concorde-decorator-subscriber"] = {
   post: api.post,
   put: api.put,
   patch: api.patch,
+  refetch: api.refetch,
+  send: api.send,
 };

package/src/docs/_decorators/get.md

@@ -1,123 +1,131 @@
 # @get
 
-Loads data through [`API.getDetailed`](../../core/utils/api.ts). The decorated property is **`ApiResult<T> | null`**: `request`, `response` (or `null` for `dataProvider(...)` resolution without HTTP), and typed `result`.
+`@get` loads data and stores the result in an optional `ApiResult<T>` property.
+The property is `undefined` until a result is available.
 
-Pass an [`Endpoint<T>`](#docs/_misc/endpoint.md/endpoint) as the first argument. Import `get` and `ApiResult` from `@supersoniks/concorde/decorators`, and `Endpoint` from `@supersoniks/concorde/utils/endpoint`.
+- `payload.result`: typed data;
+- `payload.response`: the HTTP response;
+- `payload.request`: the request that was sent.
 
-## Configuration
+## Minimal usage
 
-- **Default:** `HTML.getApiConfiguration(host)` (ancestor `serviceURL`, etc.).
-- **Second argument:** `DataProviderKey<APIConfiguration>` — config is read from the publisher at the resolved path; internal mutations trigger another GET. See [API configuration](#docs/_misc/api-configuration.md/api-configuration) for mock demos.
+```typescript
+const usersEndpoint = new Endpoint<User[]>("users");
 
-## Dynamic path
+@get(usersEndpoint)
+@state()
+payload?: ApiResult<User[]>;
+```
 
-`${prop}` on the endpoint or config key is resolved on the host. While a placeholder is `null` or `undefined`, no GET runs. Optional `skipEmptyPlaceholder: true` also blocks `""` (empty string only). Details: [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
+The first argument is always an
+[`Endpoint<T>`](#docs/_misc/endpoint.md/endpoint). API configuration is read
+from the HTML scope (`serviceURL`, token, etc.), so the component is usually
+placed below an element that provides this configuration.
 
-## Options (`GetOptions`)
+## Refetching a GET
 
-Pass as the **second** argument (scoped config) or **third** (with a configuration key). Same shape as send decorators where applicable:
+### From the component
 
-| Option | Description |
-|--------|-------------|
-| `skipEmptyPlaceholder` | Treat `""` as not ready (see [Dynamic path](#docs/_misc/dynamic-path.md/dynamic-path)). |
-| `refetchEveryMs` | Automatic polling interval (ms). `0` or omitted = no polling. |
-| `triggerKey` | `DataProviderKey` — `PublisherManager.get(...).invalidate()` on that publisher re-runs the GET. |
+Keep the decorator in a constant to access `refetch(component)`. Refetch only
+targets the instance passed as the argument, even before it has received a
+result.
 
-### Manual refetch (`triggerKey`)
+```typescript
+const usersGet = get(new Endpoint<User[]>("users"));
 
-Same pattern as [@post](#docs/_decorators/post.md/post): a publisher acts as a **signal**, independent of the response payload.
+@usersGet
+@state()
+payload?: ApiResult<User[]>;
+
+async refresh() {
+  const payload = await usersGet.refetch(this);
+  console.log(payload?.result);
+}
+```
+
+`refetch(component)` returns a `Promise<ApiResult<T> | undefined>` that resolves
+after the GET has completed.
+
+### From a method decorator
+
+The refetch can decorate a local method. The default is `after`; if the
+method returns a Promise, the GET waits for its resolution. The decorated method
+call also waits for the refetch to complete.
 
 ```typescript
-import { get, type ApiResult } from "@supersoniks/concorde/decorators";
-import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
-import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
-import { dp } from "@supersoniks/concorde/core/utils/PublisherProxy";
-
-const geoCommunesEndpoint = new Endpoint<GeoCommuneRow[]>(
-  "communes?limit=5&fields=nom,code",
-);
-const geoCommunesRefreshKey = new DataProviderKey<void>(
-  "docsDemoGeoCommunesRefresh",
-);
-
-@get(geoCommunesEndpoint, apiConfigurationKey, {
-  triggerKey: geoCommunesRefreshKey,
-})
-@state()
-payload: ApiResult<GeoCommuneRow[]> | null = null;
+import { refetch } from "@supersoniks/concorde/decorators";
+
+@refetch(usersGet)
+async reload() {
+  this.userId = "42";
+}
+```
+
+Use `{ when: "before" }` when the GET must complete before the method runs:
 
-// Same component or anywhere else:
-dp(geoCommunesRefreshKey).invalidate();
+```typescript
+@refetch(usersGet, { when: "before" })
+reloadBefore() {
+  // The refetch has completed before this method runs.
+}
 ```
 
-Prefer `triggerKey` over mutating the API configuration publisher when you only want to **reload the same URL** — no need to touch `serviceURL`, tokens, etc.
+The method decorator adds an explicit trigger; changes to dynamic endpoint
+properties and configuration publishers keep their existing automatic behavior.
 
-The docs mock adds an **`X-Fetched-At`** response header on `/docs-mock-api/geo/communes` so live demos can show when the last fetch happened (`response.headers.get("X-Fetched-At")`).
+## Options (`GetOptions`)
+
+Options are the second argument, or the third argument when an API
+configuration key is provided.
+
+- `skipEmptyPlaceholder`: blocks the GET when `${prop}` is `""`.
+- `refetchEveryMs`: automatically runs the GET again after this interval
+  (milliseconds). Omit the option, or use `0`, to disable polling.
+- `triggerKey`: a publisher whose `invalidate()` runs the GET again.
+
+With a configuration key, use:
+
+```typescript
+@get(usersEndpoint, apiConfigurationKey)
+```
 
 ## When the GET runs again
 
-- A referenced Lit property changes (endpoint path and/or config key contains `${...}`).
-- `set` on the active configuration publisher (`onInternalMutation`).
-- `triggerKey` publisher `invalidate()`.
-- `refetchEveryMs` polling (after each successful fetch).
+- when the component connects and configuration is available;
+- when a property used in `${...}` changes;
+- when a configuration publisher changes;
+- when the `triggerKey` publisher is invalidated;
+- after each response when `refetchEveryMs` is set.
+
+See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path) for
+dynamic path details.
 
 ## Import
 
 <sonic-code language="typescript">
   <template>
 import { get, type ApiResult } from "@supersoniks/concorde/decorators";
-import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
 import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
   </template>
 </sonic-code>
 
-## Minimal example
-
-Same demo service as [`sonic-queue`](../../core/components/functional/queue/queue.demo.ts) (`/docs-mock-api/geo/`). Publisher setup lives in `decorators-demo-geo.ts` and `decorators-demo-subscribe-publish-get-demos.ts`.
-
-<sonic-code language="typescript">
-  <template>
-@get(new Endpoint<User>("users/${userId}"))
-@state()
-payload: ApiResult<User> | null = null;
-  </template>
-</sonic-code>
-
-## Live demos
-
-`@get` with **`triggerKey`** — refresh button + `X-Fetched-At` timestamp in the UI:
+## Demos
 
 <sonic-code>
   <template>
     <docs-demo-sources for="demo-api-get"></docs-demo-sources>
     <demo-api-get></demo-api-get>
-  </template>
-</sonic-code>
-
-Dynamic config and endpoint path. Manual refetch is triggered **from a separate component** (same `triggerKey` publisher):
-
-<sonic-code>
-  <template>
     <docs-demo-sources for="demo-api-get-configuration-key"></docs-demo-sources>
     <demo-api-get-configuration-key></demo-api-get-configuration-key>
-    <demo-api-get-refresh-remote></demo-api-get-refresh-remote>
-  </template>
-</sonic-code>
-
-Scoped `@get` with `@publish` / `@subscribe` on the payload (see [@publish](#docs/_decorators/publish.md/publish) and [@subscribe](#docs/_decorators/subscribe.md/subscribe)) — wrap under an ancestor with `serviceURL="/docs-mock-api/geo/"`:
-
-<sonic-code>
-  <template>
-<div serviceURL="/docs-mock-api/geo/">
-  <docs-demo-sources for="demo-api-get-publish-subscribe"></docs-demo-sources>
-  <demo-api-get-publish-subscribe></demo-api-get-publish-subscribe>
-</div>
   </template>
 </sonic-code>
 
-Stale responses are ignored if the path or generation changed before the request finished.
+See [@post](#docs/_decorators/post.md/post),
+[@put](#docs/_decorators/put.md/put), and
+[@patch](#docs/_decorators/patch.md/patch) for write operations.
 
-## See also
+## Advanced
 
-- [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path)
-- [@post](#docs/_decorators/post.md/post) · [@put](#docs/_decorators/put.md/put) · [@patch](#docs/_decorators/patch.md/patch) — send decorators (same path rules)
+External invalidation is currently available through `triggerKey`; it is kept
+out of the main usage examples.

package/src/docs/_decorators/patch.md

@@ -1,45 +1,61 @@
 # @patch
 
-Sends data through [`API.patchDetailed`](../../core/utils/api.ts). Same model as [@post](#docs/_decorators/post.md/post): decorated property is **`ApiResult<T> | null`** (`request`, `response`, `result`).
+`@patch` applies a partial update with the body from a publisher. It uses the
+same model as [@post](#docs/_decorators/post.md/post):
+`Endpoint<T>`, `DataProviderKey<B>`, `ApiResult<T>`, options, and the
+`send(component)` handle.
 
-Pass an [`Endpoint<T>`](#docs/_misc/endpoint.md/endpoint) and a `DataProviderKey` for the **request body**. Import `patch` and `ApiResult` from `@supersoniks/concorde/decorators`.
+## Minimal usage
 
-## Configuration
+```typescript
+const bodyKey = new DataProviderKey<Partial<User>>("users.patch");
+const patchUser = patch(new Endpoint<User>("users/42"), bodyKey);
 
-Same as [@post](#docs/_decorators/post.md/post) / [@get](#docs/_decorators/get.md/get): scoped `HTML.getApiConfiguration(host)` or `DataProviderKey<APIConfiguration>` as third argument.
+@patchUser
+@state()
+payload?: ApiResult<User>;
+```
+
+To run the operation again from the component:
+
+```typescript
+async savePatch() {
+  await patchUser.send(this);
+}
+```
+
+`send(component)` returns a Promise resolved after the PATCH completes. See
+[@post](#docs/_decorators/post.md/post) for the method-decorator form and the
+`when: "before"` option.
 
-## Options (`PatchOptions`)
+The PATCH is also sent automatically when the body mutates, unless
+`autoPostOnBodyMutation: false` is set. The available options are described in
+[@post](#docs/_decorators/post.md/post):
 
-Same shape as `PostOptions` on [@post](#docs/_decorators/post.md/post) (`ApiSendOptions`): `refetchEveryMs`, `skipIfBodyMissing`, `autoPostOnBodyMutation`, `triggerKey`, `skipEmptyPlaceholder`. See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path) for `${sessionId}` and empty-string behaviour.
+- `autoPostOnBodyMutation`
+- `skipIfBodyMissing`
+- `refetchEveryMs`
+- `skipEmptyPlaceholder`
+- `triggerKey`
+
+Pass explicit API configuration as the third argument:
+
+```typescript
+@patch(endpoint, bodyKey, apiConfigurationKey)
+```
 
 ## Import
 
 <sonic-code language="typescript">
   <template>
 import { patch, type ApiResult } from "@supersoniks/concorde/decorators";
-import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
 import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
-  </template>
-</sonic-code>
-
-## Example
-
-<sonic-code language="typescript">
-  <template>
-const patchBodyKey = new DataProviderKey&lt;Partial&lt;Resource&gt;&gt;("resourcePatch");
-
-@patch(
-  new Endpoint&lt;Resource, { resourceId: string }&gt;("resources/${resourceId}"),
-  patchBodyKey,
-  { skipEmptyPlaceholder: true },
-)
-@state()
-payload?: ApiResult&lt;Resource&gt; | null;
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
   </template>
 </sonic-code>
 
 ## See also
 
-- [@post](#docs/_decorators/post.md/post) — POST (live demos)
-- [@put](#docs/_decorators/put.md/put) — full replacement (PUT)
+- [@post](#docs/_decorators/post.md/post) — options and triggers
+- [@put](#docs/_decorators/put.md/put) — full replacement
 - [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path)

package/src/docs/_decorators/post.md

@@ -1,93 +1,135 @@
 # @post
 
-Sends data through [`API.postDetailed`](../../core/utils/api.ts). The decorated property is **`ApiResult<T> | null`**: `request`, `response`, and typed `result`.
+`@post` sends the contents of a publisher and stores the response in an
+optional `ApiResult<T>` property. The property is `undefined` until a result
+is available.
 
-Pass an [`Endpoint<T>`](#docs/_misc/endpoint.md/endpoint) as the first argument and a `DataProviderKey` for the **request body** as the second. Import `post` and `ApiResult` from `@supersoniks/concorde/decorators`, and `Endpoint` from `@supersoniks/concorde/utils/endpoint`.
+## Minimal usage
 
-## Configuration
+Pass an `Endpoint<T>` and a `DataProviderKey<B>` for the request body.
 
-Same as [@get](#docs/_decorators/get.md/get): scoped `HTML.getApiConfiguration(host)` by default, or `DataProviderKey<APIConfiguration>` as third argument. See [API configuration](#docs/_misc/api-configuration.md/api-configuration) for mock demos.
+```typescript
+const userBodyKey = new DataProviderKey<CreateUser>("users.form");
+const createUser = post(new Endpoint<User>("users"), userBodyKey);
 
-## Optional `PostOptions` (third or fourth argument)
+@createUser
+@state()
+payload?: ApiResult<User>;
+```
 
-| Option | Description |
-|--------|-------------|
-| `refetchEveryMs` | Re-post on an interval (ms). |
-| `skipIfBodyMissing` | Skip when body publisher is `null`/`undefined` (default: `true`). |
-| `autoPostOnBodyMutation` | Re-post when the body publisher mutates (default: `true`). `false` = manual via `triggerKey.invalidate()`. |
-| `skipEmptyPlaceholder` | If `true`, a placeholder resolved to `''` blocks the request (empty string only — not `0` or `false`). See [Dynamic paths](#docs/_misc/dynamic-path.md/dynamic-path). |
-| `triggerKey` | `DataProviderKey` — `invalidate()` re-runs the POST with the current body. |
+The current body is read from `userBodyKey`. By default, the POST is sent when
+the component connects and after each body mutation. Mutations in the same
+frame are coalesced into one request.
 
-## When the POST runs again
+API configuration is read from the HTML scope, as with
+[@get](#docs/_decorators/get.md/get).
 
-- Body publisher `onInternalMutation` when `autoPostOnBodyMutation` is `true` (default). Plusieurs mutations synchrones dans la même frame sont regroupées en **un seul POST** via `requestAnimationFrame`.
-- Endpoint path dependency changes (`${sessionId}` on the host).
-- Configuration publisher mutation.
-- `triggerKey` publisher `invalidate()`.
-- `refetchEveryMs` timer (if set).
+## Sending the POST again
 
-## Import
+### From the component
 
-<sonic-code language="typescript">
-  <template>
-import { post, publish, type ApiResult } from "@supersoniks/concorde/decorators";
-import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
-import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
-  </template>
-</sonic-code>
+Keep the decorator to access `send(component)`. The body is read again when the
+operation runs.
+
+```typescript
+async saveAgain() {
+  const payload = await createUser.send(this);
+  console.log(payload?.result);
+}
+```
+
+`send()` returns a `Promise<ApiResult<T> | undefined>` that resolves after the
+operation completes. It is useful for “Save” or “Retry” buttons and can repeat
+an operation with side effects.
+
+### From a method decorator
+
+The send action can decorate a local method. It runs after the method by
+default, waits for an eventual Promise to resolve, and the decorated method
+call waits for the send to complete:
+
+```typescript
+import { send } from "@supersoniks/concorde/decorators";
+
+@send(createUser)
+async save() {
+  // Prepare local state or validate the form.
+}
+```
+
+Use `{ when: "before" }` when the send must complete before the method runs:
+
+```typescript
+@send(createUser, { when: "before" })
+saveBefore() {
+  // The POST has completed before this method runs.
+}
+```
+
+The method decorator adds an explicit send. If the method also mutates the body
+publisher, set `autoPostOnBodyMutation: false` when the decorated method must
+be the only trigger.
+
+## Options (`PostOptions`)
+
+Options are the third argument, or the fourth argument when a configuration key
+is provided.
+
+- `autoPostOnBodyMutation`: send after a body mutation (default: `true`). Set
+  it to `false` to use `send()`.
+- `skipIfBodyMissing`: skip when the body is `null` or `undefined` (default:
+  `true`).
+- `refetchEveryMs`: repeat the POST at this interval. Use it only when
+  repeating the operation is intended.
+- `skipEmptyPlaceholder`: block the request when a `${...}` placeholder is
+  `""`.
+- `triggerKey`: a publisher whose `invalidate()` sends the POST again.
+
+With a configuration key:
 
-## Minimal example
+```typescript
+@post(endpoint, userBodyKey, apiConfigurationKey)
+```
 
-Mock service: `POST /docs-mock-api/api/register` (same route as [`sonic-submit`](#core/components/functional/submit/submit.md/submit) demos). Publisher setup lives in `decorators-demo-post.ts`.
+See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path) for
+dynamic path details.
+
+## When the POST is sent
+
+- when the component connects and the body and configuration are available;
+- after a body mutation, unless `autoPostOnBodyMutation: false`;
+- when a property used in `${...}` changes;
+- when a configuration publisher changes;
+- when the `triggerKey` publisher is invalidated;
+- when `send()` is called;
+- after each response when `refetchEveryMs` is set.
+
+## Import
 
 <sonic-code language="typescript">
   <template>
-const syncRequest = new DataProviderKey&lt;SyncRequest&gt;("syncRequest");
-const syncTrigger = new DataProviderKey&lt;number&gt;("syncTrigger");
-
-@post(
-  new Endpoint&lt;SyncResponse, { sessionId: string }&gt;("sessions/${sessionId}/sync"),
-  syncRequest,
-  { triggerKey: syncTrigger },
-)
-@state()
-payload?: ApiResult&lt;SyncResponse&gt; | null;
+import { post, type ApiResult } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
   </template>
 </sonic-code>
 
-## Live demos
+## Demos
 
 <sonic-code>
   <template>
     <docs-demo-sources for="demo-api-post"></docs-demo-sources>
     <demo-api-post></demo-api-post>
-  </template>
-</sonic-code>
-
-Dynamic endpoint path — changing `sessionId` on the host re-runs the POST (`POST /docs-mock-api/api/sessions/{id}/sync`):
-
-<sonic-code>
-  <template>
     <docs-demo-sources for="demo-api-post-dynamic"></docs-demo-sources>
     <demo-api-post-dynamic></demo-api-post-dynamic>
   </template>
 </sonic-code>
 
-`@post` + `@publish` on the same property (see [@publish](#docs/_decorators/publish.md/publish)):
-
-<sonic-code>
-  <template>
-    <docs-demo-sources for="demo-api-post-publish"></docs-demo-sources>
-    <demo-api-post-publish></demo-api-post-publish>
-  </template>
-</sonic-code>
-
-Stale responses are ignored if the path or generation changed before the request finished.
-
-**Note:** plusieurs composants `@post` sur la même page qui partagent le même `bodyKey` enverront chacun une requête à chaque mutation du body — utiliser une clé par composant (voir les deux démos live ci-dessus).
-
-Path placeholders (`${sessionId}`, …): [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
+See [@put](#docs/_decorators/put.md/put) and
+[@patch](#docs/_decorators/patch.md/patch): they use the same model with a
+different HTTP method.
 
-## See also
+## Advanced
 
-- [@put](#docs/_decorators/put.md/put) · [@patch](#docs/_decorators/patch.md/patch) — same decorator model, `PUT` / `PATCH` via `putDetailed` / `patchDetailed`
+External invalidation is currently available through `triggerKey`; it is kept
+out of the main usage examples.

package/src/docs/_decorators/put.md

@@ -1,43 +1,61 @@
 # @put
 
-Sends data through [`API.putDetailed`](../../core/utils/api.ts). Same model as [@post](#docs/_decorators/post.md/post): decorated property is **`ApiResult<T> | null`** (`request`, `response`, `result`).
+`@put` replaces a resource with the body from a publisher. It uses exactly the
+same model as [@post](#docs/_decorators/post.md/post):
+`Endpoint<T>`, `DataProviderKey<B>`, `ApiResult<T>`, options, and the
+`send(component)` handle.
 
-Pass an [`Endpoint<T>`](#docs/_misc/endpoint.md/endpoint) and a `DataProviderKey` for the **request body**. Import `put` and `ApiResult` from `@supersoniks/concorde/decorators`.
+## Minimal usage
 
-## Configuration
+```typescript
+const bodyKey = new DataProviderKey<UpdateUser>("users.form");
+const updateUser = put(new Endpoint<User>("users/42"), bodyKey);
 
-Same as [@post](#docs/_decorators/post.md/post) / [@get](#docs/_decorators/get.md/get): scoped `HTML.getApiConfiguration(host)` or `DataProviderKey<APIConfiguration>` as third argument.
+@updateUser
+@state()
+payload?: ApiResult<User>;
+```
+
+To run the operation again from the component:
+
+```typescript
+async update() {
+  await updateUser.send(this);
+}
+```
+
+`send(component)` returns a Promise resolved after the PUT completes. See
+[@post](#docs/_decorators/post.md/post) for the method-decorator form and the
+`when: "before"` option.
+
+The PUT is also sent automatically when the body mutates, unless
+`autoPostOnBodyMutation: false` is set. See
+[@post](#docs/_decorators/post.md/post) for the option details:
 
-## Options (`PutOptions`)
+- `autoPostOnBodyMutation`
+- `skipIfBodyMissing`
+- `refetchEveryMs`
+- `skipEmptyPlaceholder`
+- `triggerKey`
 
-Same shape as `PostOptions` on [@post](#docs/_decorators/post.md/post) (`ApiSendOptions`): `refetchEveryMs`, `skipIfBodyMissing`, `autoPostOnBodyMutation`, `triggerKey`, `skipEmptyPlaceholder`. See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path) for `${sessionId}` and empty-string behaviour.
+Pass explicit API configuration as the third argument:
+
+```typescript
+@put(endpoint, bodyKey, apiConfigurationKey)
+```
 
 ## Import
 
 <sonic-code language="typescript">
   <template>
 import { put, type ApiResult } from "@supersoniks/concorde/decorators";
-import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
 import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
   </template>
 </sonic-code>
 
-## Example
-
-<sonic-code language="typescript">
-  <template>
-const bodyKey = new DataProviderKey&lt;UpdatePayload&gt;("resourceBody");
-
-@put(new Endpoint&lt;Resource, { resourceId: string }&gt;("resources/${resourceId}"), bodyKey)
-@state()
-payload?: ApiResult&lt;Resource&gt; | null;
-  </template>
-</sonic-code>
-
-Changing `resourceId` on the host re-runs the PUT when the path becomes ready — see [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
-
 ## See also
 
-- [@post](#docs/_decorators/post.md/post) — POST (live demos, polling, `@publish`)
-- [@patch](#docs/_decorators/patch.md/patch) — partial update (PATCH)
-- [Endpoint](#docs/_misc/endpoint.md/endpoint) · [API configuration](#docs/_misc/api-configuration.md/api-configuration)
+- [@post](#docs/_decorators/post.md/post) — options and triggers
+- [@patch](#docs/_decorators/patch.md/patch) — partial update
+- [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path)