@helia/ipns 10.1.1 → 10.2.0

package/README.md

@@ -165,6 +165,46 @@ for await (const result of name.resolve(publicKey)) {
 }
 ```
 
+## Example - Republishing an existing IPNS record
+
+It is sometimes useful to be able to republish an existing IPNS record
+without needing the private key. This allows you to extend the availability
+of a record that was created elsewhere.
+
+There should be only one republisher per IPNS key. Multiple machines
+republishing the same key flood the routers with redundant writes.
+
+```TypeScript
+import { createHelia } from 'helia'
+import { ipns } from '@helia/ipns'
+import { delegatedRoutingV1HttpApiClient } from '@helia/delegated-routing-v1-http-api-client'
+import { defaultLogger } from 'birnam'
+import { CID } from 'multiformats/cid'
+
+const helia = await createHelia()
+const name = ipns(helia)
+
+const ipnsName = 'k51qzi5uqu5dktsyfv7xz8h631pri4ct7osmb43nibxiojpttxzoft6hdyyzg4'
+const parsedCid: CID<unknown, 114, 0 | 18, 1> = CID.parse(ipnsName)
+const delegatedClient = delegatedRoutingV1HttpApiClient({
+  url: 'https://delegated-ipfs.dev'
+})({
+  logger: defaultLogger()
+})
+const record = await delegatedClient.getIPNS(parsedCid)
+
+// import the record into the local store (validates and stores it locally,
+// but does not publish it to the routers)
+await name.import(parsedCid, record)
+
+// start republishing it; throws RecordObsoleteError if the routers
+// already have a newer record for this key
+const { record: latestRecord } = await name.republish(parsedCid)
+
+// stop republishing a key
+await name.unpublish(parsedCid)
+```
+
 # Install
 
 ```console