# dblurt examples

Examples are first-class product assets for `@beblurt/dblurt`.

They are designed for humans and AI assistants:

- complete enough to copy;
- explicit about runtime and safety;
- linked from guides;
- validated where possible;
- read-only by default.

## Safety levels

| Level | Meaning |
| --- | --- |
| `read-only` | Performs RPC reads only. No signing. No broadcast. |
| `static` | Does not perform network calls. |
| `manual` | Requires a browser or manual environment. |

Broadcast examples are intentionally not part of the initial example set.

## Validation levels

| Level | Meaning |
| --- | --- |
| `run` | Can be executed directly. |
| `compile` | Should compile but may not run as-is. |
| `manual` | Requires manual browser interaction. |

## Examples

| Example | Concept | Runtime | Safety | Validation | Required RPC | Expected output |
| --- | --- | --- | --- | --- | --- | --- |
| [`node/read-head-block.cjs`](./node/read-head-block.cjs) | current Layer 1 chain state | Node.js >=18 | read-only | run | condenser_api | JSON containing `head`, `irreversible`, `time` |
| [`node/read-block-operations.cjs`](./node/read-block-operations.cjs) | Layer 1 block operation inspection | Node.js >=18 | read-only | run | condenser_api | block number, operation count and first operation types |
| [`node/read-account.cjs`](./node/read-account.cjs) | Layer 1 account state | Node.js >=18 | read-only | run | condenser_api | account name, balances and posting key count |
| [`node/read-post.cjs`](./node/read-post.cjs) | Nexus discovery + Layer 1 content read | Node.js >=18 | read-only | run | bridge + condenser_api | post identity, title and body length |
| [`node/read-active-votes.cjs`](./node/read-active-votes.cjs) | active votes for a post | Node.js >=18 | read-only | run | bridge + condenser_api | post identity and vote count |
| [`node/read-witness.cjs`](./node/read-witness.cjs) | witness information | Node.js >=18 | read-only | run | condenser_api | witness owner, signing key, votes and URL |
| [`node/read-account-history.cjs`](./node/read-account-history.cjs) | account operation history | Node.js >=18 | read-only | run | condenser_api | account name and small history summary |
| [`node/stream-block-numbers.cjs`](./node/stream-block-numbers.cjs) | bounded blockchain iteration | Node.js >=18 | read-only | run | condenser_api | three irreversible block numbers |
| [`node/read-nexus-ranked-posts.cjs`](./node/read-nexus-ranked-posts.cjs) | Nexus social/indexed query | Node.js >=18 | read-only | run | bridge | ranked post identities |
| [`node/read-nexus-community.cjs`](./node/read-nexus-community.cjs) | Nexus community discovery | Node.js >=18 | read-only | run | bridge | community name, title and subscriber count |
| [`node/read-account-summary.cjs`](./node/read-account-summary.cjs) | high-level account read model | Node.js >=18 | read-only | run | condenser_api + bridge | account, wallet, reward and social summary fields |
| [`node/estimate-vote-value.cjs`](./node/estimate-vote-value.cjs) | vote-value read model | Node.js >=18 | read-only | run | condenser_api | account, weight, mana and estimated BLURT vote value |
| [`node/build-post-operation.cjs`](./node/build-post-operation.cjs) | local content operation builder | Node.js >=18 | static | run | none | comment operation tuple fields |
| [`node/classify-retryable-error.cjs`](./node/classify-retryable-error.cjs) | typed error taxonomy | Node.js >=18 | static | run | none | classified retryable timeout metadata |
| [`node/generic-call.cjs`](./node/generic-call.cjs) | unwrapped RPC call | Node.js >=18 | read-only | run | database_api | API version data |
| [`typescript/read-account.ts`](./typescript/read-account.ts) | typed consumer compile path | TypeScript / Node.js >=18 | read-only | compile | condenser_api when executed | account summary for a configured account |
| [`browser/unpkg.html`](./browser/unpkg.html) | browser bundle read | Browser with fetch and AbortController | read-only | manual | condenser_api | page text with current head block or an error |

## Running Node examples from the repository

Build first if needed:

```bash
npm run build
```

Then run selected examples:

```bash
node examples/node/read-head-block.cjs
node examples/node/read-block-operations.cjs
node examples/node/read-account.cjs
node examples/node/read-post.cjs
node examples/node/read-nexus-ranked-posts.cjs
node examples/node/read-nexus-community.cjs
node examples/node/read-account-summary.cjs
node examples/node/estimate-vote-value.cjs
node examples/node/build-post-operation.cjs
node examples/node/classify-retryable-error.cjs
node examples/node/generic-call.cjs
```

The examples use a small loader so they work both:

- from this repository checkout; and
- after installing `@beblurt/dblurt` in a consumer project.

`examples/_load-dblurt.cjs` is an internal repository-validation helper. User-facing examples should still demonstrate the normal public package import style:

```js
const { Client } = require('@beblurt/dblurt');
```

Do not document `_load-dblurt.cjs` as an application pattern.

## TypeScript validation

`npm run docs:check` compiles the TypeScript example without emitting output. A direct local check can use:

```bash
npx tsc --noEmit --target ES2020 --module commonjs --moduleResolution node examples/typescript/read-account.ts
```

The example catalog above is intentionally checked against the files under `examples/` so new examples cannot be added without being listed.

## Source of truth

For conceptual explanations, read `../guide/`.
For AI generation rules, read `../ai/`.
For exact API signatures, use generated TypeDoc under `../docs/`.

## Future structure

If signing and broadcast examples are added later, keep the initial read-only examples clearly separated from higher-risk flows. A future layout may use:

```text
examples/
  readonly/
  signing/
  broadcast/
```

Do not add broadcast examples until the safety rules, required authorities and validation mode are explicit.