@decdn/client 0.0.0-stage → 0.1.1

package/LICENSE-APACHE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or exemplary damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/LICENSE-MIT

@@ -0,0 +1,19 @@
+Copyright 2026 deCDN Contributors
+
+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,309 @@
-# Temporary Holding Version
+<!-- markdownlint-disable-file MD033 MD041 -->
+<p align="center">
+  <a href="https://decdn.org">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/decdn/decdn/main/.github/assets/wordmark-dark.svg">
+      <img alt="deCDN" src="https://raw.githubusercontent.com/decdn/decdn/main/.github/assets/wordmark-light.svg" width="150">
+    </picture>
+  </a>
+</p>
 
-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.
+<h1 align="center">@decdn/client</h1>
+
+<h3 align="center">TypeScript client for deCDN: verified fetches, bundles, loopback capabilities and namespace pointers.</h3>
+
+<p align="center">
+  <a href="https://github.com/decdn/sdk-typescript/actions/workflows/ci.yml?query=branch%3Amain"><img src="https://img.shields.io/github/actions/workflow/status/decdn/sdk-typescript/ci.yml?branch=main&label=CI&logo=github" alt="CI"></a>
+  <a href="https://github.com/decdn/sdk-typescript/actions/workflows/codeql.yml?query=branch%3Amain"><img src="https://img.shields.io/github/actions/workflow/status/decdn/sdk-typescript/codeql.yml?branch=main&label=CodeQL&logo=github" alt="CodeQL"></a>
+  <a href="https://github.com/decdn/sdk-typescript/actions/workflows/gateway-releases.yml"><img src="https://img.shields.io/github/actions/workflow/status/decdn/sdk-typescript/gateway-releases.yml?branch=main&label=gateway%20releases&logo=github" alt="Contract suite against released gateways"></a>
+  <a href="https://www.npmjs.com/package/@decdn/client"><img src="https://img.shields.io/npm/v/@decdn/client?logo=npm" alt="npm"></a>
+  <a href="https://bundlejs.com/?q=%40decdn%2Fclient"><img src="https://img.shields.io/bundlejs/size/@decdn/client?label=minzip" alt="Bundle size"></a>
+  <a href="https://www.npmjs.com/package/@decdn/client"><img src="https://img.shields.io/npm/types/@decdn/client?logo=typescript&logoColor=white" alt="Types: TypeScript"></a>
+  <a href="#compatibility"><img src="https://img.shields.io/node/v/@decdn/client?logo=node.js&logoColor=white" alt="Node.js"></a>
+  <a href="#compatibility"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fdecdn%2Fsdk-typescript%2Fmain%2Fpackage.json&query=%24.decdn.gatewayFloor&label=decdn%20gateway&prefix=%E2%89%A5%20v" alt="decdn gateway floor"></a>
+  <a href="#license"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache--2.0-blue" alt="License: MIT OR Apache-2.0"></a>
+  <a href="https://www.conventionalcommits.org"><img src="https://img.shields.io/badge/Conventional%20Commits-1.0.0-yellow" alt="Conventional Commits"></a>
+  <a href="https://discord.gg/vVbNswKVGX"><img src="https://img.shields.io/badge/chat-Discord-5865F2?logo=discord&logoColor=white" alt="Discord"></a>
+</p>
+
+<h3 align="center">
+  <a href="https://decdn.org">Website</a> ·
+  <a href="https://docs.decdn.org">Docs</a> ·
+  <a href="https://github.com/decdn/decdn/blob/main/adr/appendix-gateway.md">Gateway spec</a> ·
+  <a href="https://github.com/decdn/decdn">deCDN</a> ·
+  <a href="https://discord.gg/vVbNswKVGX">Discord</a>
+</h3>
+
+TypeScript client for [deCDN](https://github.com/decdn/decdn), for Node.js
+20.19+ and evergreen browsers. It speaks HTTP to a `decdn gateway`, which pays
+for every pull and verifies it, and it hashes the bytes again with BLAKE3
+wherever it holds a whole blob named by its hash. No native code, no iroh, no
+wallet library.
+
+- **Verified streaming.** A blob, or a whole bundle entry, is hashed with
+  BLAKE3 as it streams; a body that does not hash to its name ends with
+  `HASH_MISMATCH` instead of `done`. Ranges and rendered pages are
+  `"skipped"` ([Verification](#verification)).
+- **Bundles.** Entries are checked against the bundle manifest, which is
+  itself verified and cached per client.
+- **Byte ranges** of sized entries, for large files such as model weights. A
+  window does not hash to anything, so its `verified` is `"skipped"`.
+- **Pages on a site origin.** `DecdnClient.open()` with no URL works from a
+  page on a bundle's site origin (`<hash32>.<host>`); a namespace host needs
+  `gatewayUrl`.
+- **Loopback gateways.** Mint delegate keys and register capabilities on a
+  local `decdn gateway`.
+- **Namespace pointers.** Point a `PublisherRegistry` namespace at a bundle on
+  a public gateway, signing EIP-712 typed data with a private key or a
+  viem-style `signTypedData(typedData)` signer.
+- **Small and typed.** ESM, CJS and declarations; runtime dependencies
+  `@noble/hashes` and `@noble/curves` only; namespaces, seq, caps and expiries
+  are `bigint`.
+
+## Contents
+
+- [Install](#install)
+- [Gateways](#gateways)
+- [Compatibility](#compatibility)
+- [Public gateway](#public-gateway)
+- [Loopback gateway (Node)](#loopback-gateway-node)
+- [Pages on a site origin](#pages-on-a-site-origin)
+- [Verification](#verification)
+- [Errors](#errors)
+- [Namespace pointers](#namespace-pointers)
+- [API at a glance](#api-at-a-glance)
+- [Development](#development)
+- [License](#license)
+
+## Install
+
+```sh
+pnpm add @decdn/client
+# or
+npm install @decdn/client
+# or
+yarn add @decdn/client
+```
+
+## Gateways
+
+The client talks to one of two kinds of gateway:
+
+| Gateway                                                  | Where it runs                                                     | Who pays                                          |
+| -------------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------- |
+| Public (`decdn gateway --public-url https://decdn.link`) | Node or any web page                                              | The operator's pool, within a daily allowance     |
+| Loopback (`decdn gateway`, `http://127.0.0.1:8484`)      | Node with the gateway token, or a page on one of its site origins | The capability registered for the requesting host |
+
+The gateway's HTTP contract is
+[appendix-gateway](https://github.com/decdn/decdn/blob/main/adr/appendix-gateway.md);
+bundles and their manifests are
+[appendix-bundles](https://github.com/decdn/decdn/blob/main/adr/appendix-bundles.md).
+
+## Compatibility
+
+Node.js 20.19 or later, and evergreen browsers.
+
+| `@decdn/client` | `decdn gateway`                                                                                                                                                                                   |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 0.1             | v0.3.0 or later for browser pages and public gateways ([cross-origin reads](https://github.com/decdn/decdn/blob/main/adr/appendix-gateway.md#cross-origin-reads)); any loopback gateway from Node |
+
+CI runs the contract suite against the floor and the latest decdn release, with
+each release's signed binaries ([CONTRIBUTING.md](CONTRIBUTING.md#release-gateways)).
+
+## Public gateway
+
+```ts
+import { DecdnClient } from "@decdn/client";
+
+const client = await DecdnClient.open({ gatewayUrl: "https://decdn.link" });
+
+// A blob, streamed and hashed as it arrives.
+const blob = await client.get("decdn:<64 hex>");
+blob.verified; // true
+const bytes = await blob.bytes(); // rejects with HASH_MISMATCH on bad bytes
+
+// One file of a bundle, checked against the bundle's manifest.
+const page = await client.get("decdn:<manifest hash>/docs/index.html");
+const text = await page.text();
+
+// A window of a sized entry: 206, not verifiable.
+const part = await client.get("decdn:<manifest hash>/model.bin", {
+  range: { offset: 0, length: 1 << 20 },
+});
+part.contentRange; // { offset, length, size }
+```
+
+The same code runs in a browser on any origin: a public gateway answers every
+origin, `Range` preflights included.
+
+## Loopback gateway (Node)
+
+A loopback gateway pays with a capability a pool owner issued to one of its
+delegate keys. Mint the delegate, have the owner assign it, and register it
+for the host your requests name:
+
+```ts
+import { DecdnClient } from "@decdn/client";
+import { readLoopbackToken } from "@decdn/client/node";
+
+const client = await DecdnClient.open({
+  gatewayUrl: "http://127.0.0.1:8484",
+  token: await readLoopbackToken(), // ~/.decdn/gateway/token
+  host: "example.com", // sent as x-decdn-host
+});
+
+const { address } = await client.loopback.delegate();
+// The pool owner: decdn pool assign --pool <id> --signer <address> ...
+await client.loopback.registerCapability({
+  capability: "dcap1:...",
+  scope: "example.com",
+});
+
+const r = await client.get("decdn:<64 hex>");
+```
+
+`client.loopback.capabilities()` lists what the gateway holds. Without a
+covering capability a request fails with `PAYMENT_REQUIRED`. A `dcap1:` token
+decodes offline with `parseCapability`.
+
+The SDK does not start the gateway. Run it yourself (`decdn gateway`, or the
+`decdn/decdn` Docker image). `open()` treats a `localhost`, `127.0.0.1` or
+`::1` URL as a loopback gateway; a public gateway you run locally needs
+another host name, such as `decdn.localhost`.
+
+## Pages on a site origin
+
+A bundle opened as a website lives on its own origin,
+`https://<hash32>.decdn.link/` or `http://<hash32>.localhost:8484/`. A page
+there opens the client with no URL:
+
+```ts
+const client = await DecdnClient.open();
+client.context; // "site"
+const style = await client.get("/css/site.css"); // its own bundle, verified
+const other = await client.get("decdn:<64 hex>"); // through /_decdn/
+```
+
+On a namespace host (`https://<ns>.decdn.link/`), pass the gateway URL so
+the host is recognised: `DecdnClient.open({ gatewayUrl: "https://decdn.link" })`.
+The bundle there is whatever the pointer names, so the page's own paths are
+not verified and `manifest()` needs a hash.
+
+A page on a loopback site origin reaches the gateway's delegate and capability
+API with a second client on the gateway itself:
+`DecdnClient.open({ gatewayUrl: "http://127.0.0.1:8484" })`. A loopback
+`gatewayUrl` opens a `loopback` client from any page; without the token, which
+a page cannot send, it reaches that API alone.
+
+## Verification
+
+`get` takes `verify: "auto" | true | false` (default `"auto"`, or the
+client's own default from `open`). `response.verified` says what happened:
+
+| Request                     | `verified`  | How                                                                                                                |
+| --------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------ |
+| A blob by hash              | `true`      | The whole body hashes to the URI's hash.                                                                           |
+| A bundle entry              | `true`      | The client reads the bundle manifest (cached per client, itself verified) and the body hashes to the entry's hash. |
+| A page or stylesheet entry  | `true`      | A site rewrites HTML and CSS as it serves them, so the client fetches these by their entry hash instead.           |
+| A `range` of a bundle entry | `"skipped"` | A window does not hash to anything. A blob has no declared size, so a range on one is refused with `CONFIG`.       |
+| A bundle's index or listing | `"skipped"` | The gateway renders it.                                                                                            |
+| Any, with `verify: false`   | `false`     | Nothing is hashed and no manifest is read.                                                                         |
+
+`verify: true` refuses a request that cannot be verified with `CONFIG`.
+
+A verified body is hashed as it streams: `response.body` ends with an error
+(`HASH_MISMATCH`, or `TRUNCATED` when the gateway cuts it) instead of `done`,
+and `bytes()`, `text()` and `json()` reject. Bytes read before the end are not
+yet verified; act on them only once the stream is done.
+
+## Errors
+
+Every failure is a `DecdnError` with a stable `code`:
+
+| Code                                                                                                       | When                                                                                                        | Extra fields                    |
+| ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------- |
+| `PAYMENT_REQUIRED`                                                                                         | 402: the allowance is spent, the entry does not fit what is left, or no loopback capability covers the host | `retryAfterSecs`, `fallbackUri` |
+| `POOL_UNFUNDED`                                                                                            | 503: the gateway's pool cannot pay                                                                          | `retryAfterSecs`, `fallbackUri` |
+| `RANGE_NOT_SATISFIABLE`                                                                                    | 416                                                                                                         | `size`                          |
+| `CONFLICT`                                                                                                 | 409: a pointer `seq` that is not newer, a capability already registered                                     | `seq`                           |
+| `NOT_FOUND`, `UNAUTHORIZED`, `FORBIDDEN`, `RATE_LIMITED`, `UPSTREAM`, `PAYLOAD_TOO_LARGE`, `UNPROCESSABLE` | 404, 401, 403, 429, 502, 413, 422                                                                           | `status`, `body`                |
+| `BAD_URI`                                                                                                  | A `decdn:` URI that does not parse, or 400                                                                  |                                 |
+| `HASH_MISMATCH`, `TRUNCATED`                                                                               | The body does not hash to its hash, or is shorter or longer than declared                                   |                                 |
+| `MALFORMED_MANIFEST`, `BAD_CAPABILITY`                                                                     | A manifest or `dcap1:` token that does not decode                                                           |                                 |
+| `NETWORK`, `CONFIG`, `HTTP`                                                                                | The gateway is unreachable; the client cannot do what was asked; another status                             |                                 |
+
+`fallbackUri` is the canonical `decdn:` URI: fetch it with a paying client of
+your own (`decdn get <uri>`), or wait `retryAfterSecs`. The SDK retries
+nothing on its own; `get(uri, { retry: true })` waits out one `Retry-After`
+and tries once more.
+
+## Namespace pointers
+
+On a public gateway, the owner of a namespace on the `PublisherRegistry`
+points it at a bundle, and `https://<ns>.<host>/` serves that bundle:
+
+```ts
+const client = await DecdnClient.open({
+  gatewayUrl: "https://decdn.link",
+  pointer: { chainId: 421614, publisherRegistry: "0x..." },
+});
+const set = await client.pointer.set({
+  namespace: 42n,
+  root: "decdn:<manifest hash>/",
+  signer: { privateKey: "0x..." }, // or a viem account: anything with signTypedData
+});
+set.url; // https://42.decdn.link/
+```
+
+The pointer is EIP-712 typed data (`pointerTypedData` gives it to a wallet),
+`seq` defaults to the current Unix second, and the gateway takes only a `seq`
+above the last one it holds from the same signer. The chain id and registry
+are the deployment the gateway verifies against.
+
+## API at a glance
+
+| Export                                                                          | What it does                                                                                                                                                          |
+| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `DecdnClient.open(opts?)`                                                       | Opens a client on a public or loopback gateway, or on the site origin a page is served from                                                                           |
+| `client.get(uri, opts?)`                                                        | Fetches a blob, a bundle, a bundle entry or a range (or, on a site page, a path of its own bundle) as a `DecdnResponse` (`verified`, `body`, `bytes`, `text`, `json`) |
+| `client.head(uri)`                                                              | The size, hash and content type of what a URI names, without its bytes                                                                                                |
+| `client.resolve(uri)`                                                           | A URI's kind, hash, bare and site URLs, and its manifest entry (reads the manifest for a bundle or entry)                                                             |
+| `client.manifest(hashOrUri?, signal?)`                                          | A bundle's verified manifest, cached per client; on a site page, the page's own bundle when omitted                                                                   |
+| `client.siteUrl(uri)`, `client.namespaceUrl(ns)`                                | The site URL of a bundle or entry; the URL a namespace's pointer serves at (`https://<ns>.<host>/`). Neither makes a request                                          |
+| `client.loopback.delegate()`                                                    | Mints a delegate key on a loopback gateway, held for 15 minutes unless a capability claims it                                                                         |
+| `client.loopback.registerCapability({ capability, scope })`, `.capabilities()`  | Registers a `dcap1:` capability for a scope (`example.com`, `*.example.com` or `*`); lists the capabilities the gateway holds (needs the token)                       |
+| `client.pointer.set(args)`                                                      | Signs and publishes a namespace pointer on a public gateway                                                                                                           |
+| `pointerTypedData`, `pointerSigningHash`, `signPointer`, `recoverPointerSigner` | The pointer's EIP-712 typed data and signing hash, its signature, and the signer a signature recovers to                                                              |
+| `parseUri`, `formatUri`                                                         | Parse and canonically format a `decdn:` URI, following the Rust client's grammar exactly (`BAD_URI` on anything it refuses)                                           |
+| `hashToBase32`, `base32ToHash`                                                  | A hash to and from its site label                                                                                                                                     |
+| `blake3Hex`, `createBlake3`                                                     | BLAKE3, one-shot and incremental                                                                                                                                      |
+| `parseManifest`, `parseCapability`                                              | Decodes a v1 bundle manifest, checking its hash when given one; decodes a `dcap1:` token without checking its signature                                               |
+| `DecdnError`                                                                    | Every failure, with a stable `code` ([Errors](#errors))                                                                                                               |
+| `readLoopbackToken`, `defaultDataDir`                                           | From `@decdn/client/node`: the loopback gateway's token and data dir (`~/.decdn/gateway`)                                                                             |
+
+Namespaces, sequence numbers, caps and expiries are `bigint`.
+
+## Development
+
+```sh
+pnpm install
+pnpm lint            # eslint, prettier, tsc
+pnpm test            # unit tests and the contract suite against the fake gateway
+pnpm test:browser    # Chromium smoke run (pnpm exec playwright install chromium-headless-shell)
+pnpm build           # dist/: ESM, CJS and types
+```
+
+`test/fake-gateway.ts` reproduces the gateway's HTTP contract. The contract
+suite in `test/contract` runs against it by default, and against a real
+gateway in decdn's CI
+([`gateway_sdk.rs`](https://github.com/decdn/decdn/blob/main/crates/e2e/tests/gateway_sdk.rs)),
+so the two cannot drift apart. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+Releases are cut from signed `v*` tags ([RELEASING.md](RELEASING.md)); the
+keys that sign them are in [`KEYS`](KEYS) (`gpg --import KEYS`, then
+`git verify-tag vX.Y.Z`).
+
+## License
+
+Dual-licensed under either [MIT](LICENSE-MIT) or [Apache-2.0](LICENSE-APACHE),
+at your option.