docs: API reference and getting-started guide for developers.pezkuwichain.io (#21)

* docs: generate the API reference for developers.pezkuwichain.io

Add TypeDoc (0.28.20) and `yarn docs`, which builds the reference for the
nine public API packages from src/ into build-docs/, with a landing page
and a getting-started guide whose examples were run against the live
network. The PR workflow builds it so a broken doc comment or config is
caught before merge.

docs/ held only a redirect to polkadot.js.org; it now holds the guide
sources. The README, packages/api/README.md and three CHANGELOG entries
linked to js.pezkuwichain.app, a domain that is not ours and is listed
for sale; they now point to developers.pezkuwichain.io, the Pezkuwi
Portal, or the upstream polkadot.js.org pages the entries came from.

* ci(docs): deploy the reference to developers.pezkuwichain.io

On every master push that changes the generated reference, build it with
`yarn docs` and publish it to the web host the same way pezkuwi-apps
publishes the portal: an approved production environment holds the deploy
key, the bundle is unpacked into releases/<sha>, and going live is one
rename of the current symlink. The switch is checked through nginx for the
public name (deploy sha, index, main.js, search index) and rolled back if
the new release is not served. workflow_dispatch with rollback_to makes an
earlier release live again.

Release-bot version bumps ([CI Skip]) and changes that cannot affect the
output do not ask for an approval.

docs/404.html

@@ -1,12 +0,0 @@
-<!DOCTYPE html>
-<html>
-  <head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="initial-scale=0.5, maximum-scale=1">
-    <meta http-equiv="refresh" content="0;URL='https://polkadot.js.org/docs/api/'" />
-    <title>Redirecting to https://polkadot.js.org/docs/api/</title>
-  </head>
-  <body>
-    Redirecting to <a href="https://polkadot.js.org/docs/api/">https://polkadot.js.org/docs/api/</a>
-  </body>
-</html>

docs/getting-started.md

@@ -0,0 +1,111 @@
+---
+title: Getting started
+---
+
+# Getting started
+
+Every example on this page was run against the live PezkuwiChain network,
+except the final `signAndSend`, which needs a funded account. Each runs as an
+ES module (`node example.mjs`) on Node.js 18 or newer, and works the
+same way in a browser bundle.
+
+## Install
+
+```bash
+npm install @pezkuwi/api @pezkuwi/keyring
+```
+
+## Connect
+
+```js
+import { ApiPromise, WsProvider } from '@pezkuwi/api';
+
+const api = await ApiPromise.create({
+  provider: new WsProvider('wss://rpc.pezkuwichain.io')
+});
+
+const [chain, nodeName, nodeVersion] = await Promise.all([
+  api.rpc.system.chain(),
+  api.rpc.system.name(),
+  api.rpc.system.version()
+]);
+
+console.log(`Connected to ${chain} via ${nodeName} v${nodeVersion}`);
+```
+
+`ApiPromise.create` resolves once the API has fetched the runtime metadata, so
+from that point `api.query`, `api.tx` and `api.consts` reflect exactly what the
+connected chain supports.
+
+## Read chain state
+
+```js
+const header = await api.rpc.chain.getHeader();
+console.log(`Best block: #${header.number}`);
+
+const { tokenSymbol, tokenDecimals } = api.registry.getChainProperties().toHuman();
+console.log('Token:', tokenSymbol, 'decimals:', tokenDecimals); // [ 'HEZ' ] [ '12' ]
+
+const address = '5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty';
+const { data: { free } } = await api.query.system.account(address);
+console.log(`Free balance: ${free} TYR`);
+```
+
+HEZ has 12 decimals: 1 HEZ = 10^12 TYR. Balances come back in TYR, the smallest
+unit.
+
+## Follow new blocks
+
+```js
+const unsubscribe = await api.rpc.chain.subscribeNewHeads((head) => {
+  console.log(`New block #${head.number}`);
+});
+
+// later
+unsubscribe();
+```
+
+## Build, price and send a transfer
+
+```js
+import { Keyring } from '@pezkuwi/keyring';
+
+const keyring = new Keyring({ type: 'sr25519' });
+const sender = keyring.addFromUri('//Alice'); // a development key: never hold real funds with it
+
+const recipient = '5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty';
+const amount = 10n ** 12n; // 1 HEZ
+
+const tx = api.tx.balances.transferKeepAlive(recipient, amount);
+
+const { partialFee } = await tx.paymentInfo(sender);
+console.log(`Estimated fee: ${partialFee} TYR`);
+
+// Submitting needs a funded account:
+const unsub = await tx.signAndSend(sender, ({ status, dispatchError }) => {
+  if (dispatchError) {
+    console.error(dispatchError.toString());
+  }
+  if (status.isInBlock) {
+    console.log(`Included in block ${status.asInBlock}`);
+  }
+  if (status.isFinalized) {
+    unsub();
+  }
+});
+```
+
+`transferKeepAlive` refuses a transfer that would take the sender below the
+existential deposit and reap the account. Use `transferAllowDeath` only when
+that is what you want.
+
+## Disconnect
+
+```js
+await api.disconnect();
+```
+
+## Other networks
+
+The same code works against any endpoint listed on the [home page](index.md),
+for example `wss://asset-hub-rpc.pezkuwichain.io` for PezkuwiChain Asset Hub.

docs/index.html

@@ -1,12 +0,0 @@
-<!DOCTYPE html>
-<html>
-  <head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="initial-scale=0.5, maximum-scale=1">
-    <meta http-equiv="refresh" content="0;URL='https://polkadot.js.org/docs/api/'" />
-    <title>Redirecting to https://polkadot.js.org/docs/api/</title>
-  </head>
-  <body>
-    Redirecting to <a href="https://polkadot.js.org/docs/api/">https://polkadot.js.org/docs/api/</a>
-  </body>
-</html>

docs/index.md

@@ -0,0 +1,46 @@
+# Pezkuwi API
+
+`@pezkuwi/api` is the JavaScript and TypeScript library for talking to PezkuwiChain
+and other Bizinikiwi-based networks. Your application loads it and connects
+straight to a node's RPC endpoint: there is no server in between.
+
+- New here? Start with [Getting started](getting-started.md).
+- Looking for a class or a method? Use the search box, or browse the packages below.
+
+## Install
+
+```bash
+npm install @pezkuwi/api
+```
+
+## Packages
+
+| Package | What it does |
+|---|---|
+| `@pezkuwi/api` | `ApiPromise` and `ApiRx`, the entry points most applications use |
+| `@pezkuwi/api-base` | The base class both APIs share |
+| `@pezkuwi/api-derive` | Derived queries that combine several storage reads into one answer |
+| `@pezkuwi/api-contract` | Deploying and calling ink! smart contracts |
+| `@pezkuwi/rpc-core` | The typed JSON-RPC layer |
+| `@pezkuwi/rpc-provider` | `WsProvider`, `HttpProvider` and the light-client provider |
+| `@pezkuwi/types` | The runtime type registry and every chain type |
+| `@pezkuwi/types-codec` | SCALE codec primitives (`Struct`, `Enum`, `Vec`, `Compact`, …) |
+| `@pezkuwi/types-create` | Building types from their definitions |
+
+Keys and signing live in `@pezkuwi/keyring`, and hashing and address helpers in
+`@pezkuwi/util-crypto`. Both come from the
+[pezkuwi-common](https://github.com/pezkuwichain/pezkuwi-common) repository.
+
+## Public endpoints
+
+| Network | WebSocket RPC |
+|---|---|
+| PezkuwiChain relay | `wss://rpc.pezkuwichain.io` |
+| PezkuwiChain Asset Hub | `wss://asset-hub-rpc.pezkuwichain.io` |
+| Zagros Asset Hub (test network) | `wss://zagros-asset-hub-rpc.pezkuwichain.io` |
+
+## Source
+
+The code is at [github.com/pezkuwichain/pezkuwi-api](https://github.com/pezkuwichain/pezkuwi-api).
+This reference is generated from it, so what you read here is what the published
+packages contain.