@fastxyz/fastid-sdk 0.1.0 → 0.2.0

package/README.md

@@ -7,9 +7,18 @@ unchanged. The package is licensed under Apache-2.0, as specified in this
 directory's LICENSE, independently of the monorepo's root license.
 Copyright (c) Pi Squared, Inc.
 
-## Install before the first npm publication
+## Install
 
-From the public fast-sdk checkout:
+The [public package](https://www.npmjs.com/package/@fastxyz/fastid-sdk) is
+available on npm. Pin a version in an agent project:
+
+```sh
+npm install @fastxyz/fastid-sdk@0.2.0
+```
+
+It builds and runs without access to the private Fast ID repository. The
+following source-tarball path is only for testing an unpublished change from a
+public `fast-sdk` checkout:
 
 ```sh
 corepack pnpm install --frozen-lockfile
@@ -19,9 +28,6 @@ corepack pnpm --filter @fastxyz/fastid-sdk pack --pack-destination /tmp/fastid-s
 npm install /tmp/fastid-sdk-pack/fastxyz-fastid-sdk-*.tgz
 ```
 
-After npm publication, the package name is `@fastxyz/fastid-sdk`. Building and
-using it requires no access to the private Fast ID repository.
-
 ```ts
 import { IdClient, KeySigner } from '@fastxyz/fastid-sdk';
 
@@ -30,6 +36,19 @@ const client = new IdClient({ network: 'fast:testnet', signer });
 const availability = await client.availability('agent.sdk');
 ```
 
+For lookups only (for example, turning `alice.smith` into the `fast1...` address
+to pay), use `IdReader`, which needs no signer and applies the same response
+checks (network and name binding) as `IdClient`:
+
+```ts
+import { IdReader, isCanonicalName } from '@fastxyz/fastid-sdk';
+
+const reader = new IdReader({ network: 'fast:mainnet' });
+if (isCanonicalName('alice.smith')) {
+  const { address } = await reader.resolve('alice.smith'); // fast1...
+}
+```
+
 The client supports public identity reads, name/website/GitHub/ORCID/X claims,
 DOI imports, profile updates, revocation, sealed reports and sharing URLs. Use
 `fast:mainnet` when intending to use production. Paid operations use the supplied
@@ -50,6 +69,154 @@ known provider identity; the SDK polls the persisted proof, without receiving
 OAuth callbacks or tokens. See the served [agent guide](https://id.fast.xyz/AGENTS.md)
 for the full capability and recovery contracts.
 
+## Claim a name and read it back (testnet)
+
+This example **submits a Fast transaction that may carry a network fee**. Use
+only a testnet key whose owner has authorized the particular claim and any
+applicable fee, and fund that address when a fee applies. Never put a private
+key in the source file or print it. A production integration can supply its own
+authorized `Signer` instead of loading a key from the environment.
+
+1. Check the current network fee before authorizing the operation:
+
+   | Network | Public `GET /v1/network-info` |
+   |---|---|
+   | Testnet | https://testnet.api.fast.xyz/proxy-rest/v1/network-info |
+   | Mainnet | https://api.fast.xyz/proxy-rest/v1/network-info |
+
+   Confirm `data.network_id`, then find the entry in `data.fees.entries` whose
+   `token_id` equals `data.fees.default`. Its `fixed_amount` is a decimal string
+   in **atomic units**, not a display amount. For a nonzero fee, fetch the token
+   metadata and decimals from `GET /v1/tokens?token_ids=<default>` on the same
+   `proxy-rest` origin. An empty authoritative fee list or a zero default fee
+   means no fee; a failed or malformed request does **not** mean no fee. The SDK
+   resolves the authoritative schedule during the claim and refuses unavailable
+   or ambiguous fee data. This preview does not pin the schedule or enforce a
+   spending ceiling if the network changes it before submission.
+
+2. Provide `FAST_ID_NAME`, a privately held `FAST_ID_PRIVATE_KEY` (a bare
+   64-character hex Ed25519 key), and `FAST_ID_JOURNAL` (a new, private file on
+   persistent storage) to a Node 20.19+ process. Save the following as
+   `claim.mjs` and run `node claim.mjs` **once for this authorization**. The
+   journal file must not already exist; do not use a newly generated, unfunded
+   key for a paid claim or rerun this script to retry a late read-back.
+
+   ```js
+   import { constants, closeSync, fsyncSync, openSync, writeFileSync } from 'node:fs';
+   import { dirname } from 'node:path';
+   import {
+     IdClient,
+     IndeterminateSubmissionError,
+     KeySigner,
+     RegistrationPendingError,
+   } from '@fastxyz/fastid-sdk';
+
+   const name = process.env.FAST_ID_NAME;
+   const privateKey = process.env.FAST_ID_PRIVATE_KEY;
+   const journalPath = process.env.FAST_ID_JOURNAL;
+   if (!name || !privateKey || !journalPath) {
+     throw new Error('Missing name, authorized key, or journal path');
+   }
+
+   const signer = await KeySigner.fromPrivateKey(privateKey);
+   const client = new IdClient({ network: 'fast:testnet', signer });
+
+   // Advisory read. claimName performs its own fresh, fail-closed preflight.
+   const availability = await client.availability(name);
+   if (!availability.available) throw new Error('Name is not available');
+
+   // An existing journal stops this script before it can submit another claim.
+   const journal = openSync(
+     journalPath,
+     constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_APPEND,
+     0o600,
+   );
+   const save = (event) => {
+     writeFileSync(journal, `${JSON.stringify(event)}\n`);
+     fsyncSync(journal);
+   };
+   try {
+     save({ stage: 'attempting', network: 'fast:testnet', address: signer.address, name });
+     // Persist the new directory entry before the paid request. Any failure aborts.
+     const journalDirectory = openSync(dirname(journalPath), constants.O_RDONLY);
+     try {
+       fsyncSync(journalDirectory);
+     } finally {
+       closeSync(journalDirectory);
+     }
+
+     let claim;
+     try {
+       claim = await client.claimName(name); // Signs and submits one claim.
+     } catch (error) {
+       if (error instanceof RegistrationPendingError) {
+         save({ stage: 'registration_pending', pending: error.pending });
+       } else if (error instanceof IndeterminateSubmissionError) {
+         save({
+           stage: 'indeterminate',
+           network: error.network,
+           address: error.address,
+           nonce: error.nonce?.toString(),
+           txIdHex: error.txIdHex,
+         });
+       }
+       throw error;
+     }
+     save({
+       stage: 'registered',
+       network: 'fast:testnet',
+       address: signer.address,
+       name,
+       nonce: claim.nonce,
+       txIdHex: claim.txIdHex,
+     });
+
+     // These reads can fail without losing the already saved claim transaction ID.
+     const identity = await client.identity(signer.address);
+     const record = await client.resolve(name);
+     if (
+       identity.name !== name ||
+       identity.name_claim_tx !== claim.txIdHex ||
+       record.name !== name ||
+       record.address !== signer.address ||
+       record.name_claim_tx !== claim.txIdHex
+     ) {
+       throw new Error('Claim not yet visible in reads; retry reads, not payment');
+     }
+
+     console.log({
+       txIdHex: claim.txIdHex,
+       profileUrl: client.share.profileUrl(name),
+     });
+   } finally {
+     closeSync(journal);
+   }
+   ```
+
+   If `claimName()` throws `RegistrationTerminalError`, settlement has completed
+   and the error reports `feeSpent === true` (the network fee may have been
+   charged). This example cannot persist a transaction ID from that error, so
+   the journal remains at `attempting`; its existing-file guard prevents
+   rerunning the script. Do not remove or replace
+   the journal or submit another claim. Manually reconcile using trusted
+   transaction evidence before any further payment.
+
+3. This read-back confirms what the Fast ID index currently reports; it is not
+   an independent validator-quorum proof of on-chain settlement. If it is not
+   yet visible, repeat **only** `identity` and `resolve` with the `registered`
+   journal entry's name, address and transaction ID; never rerun `claim.mjs`
+   or call `claimName` merely because a read is late. For
+   `registration_pending`, pass the saved `pending` record to
+   `client.retryRegistration(...)`; this retries registration only. For
+   `indeterminate`, the journal retains available network, address, nonce and
+   transaction ID hints; reconcile before any further paid action. The SDK's
+   `recoveryEnvelope` is an in-memory structured clone, **not** a JSON-safe
+   persistence format, and these hints may be insufficient to reconcile on
+   their own. If a journal write fails after submission, stop and investigate;
+   never interpret that failure or a missing read as permission to pay again.
+   See the [testnet agent guide](https://testnet.id.fast.xyz/AGENTS.md) for the remaining
+   recovery and evidence limits.
+
 ## Development and web parity
 
 ```sh

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { CLAIM_DATA_KINDS, CLAIM_DATA_V2_MAX_BYTES, CLAIM_DATA_V2_SCHEMA, claimDataHex, encodeClaimDataV2, isCanonicalClaimValue, isClaimDataKind, type ClaimDataKind, } from "./claim-data.js";
 export { type PendingRegistration, type RegisteredClaim, type RevocableClaimKind, } from "./claims.js";
 export { IdClient, type IdClientOptions } from "./client.js";
+export { IdReader, type IdReaderOptions } from "./reader.js";
+export { isCanonicalName } from "./name.js";
 export * from "./errors.js";
 export { HttpError } from "./http.js";
 export { type IdNetwork } from "./networks.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,oBAAoB,EACpB,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,KAAK,aAAa,GACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAC7D,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,wBAAwB,EAC7B,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,UAAU,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,oBAAoB,EACpB,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,KAAK,aAAa,GACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,eAAe,EACpB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,mBAAmB,GACzB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,KAAK,sBAAsB,EAC3B,KAAK,eAAe,EACpB,KAAK,aAAa,EAClB,KAAK,gBAAgB,EACrB,KAAK,wBAAwB,EAC7B,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,mBAAmB,GACzB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,UAAU,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,eAAe,EACf,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,KAAK,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -1,5 +1,7 @@
 export { CLAIM_DATA_KINDS, CLAIM_DATA_V2_MAX_BYTES, CLAIM_DATA_V2_SCHEMA, claimDataHex, encodeClaimDataV2, isCanonicalClaimValue, isClaimDataKind, } from "./claim-data.js";
 export { IdClient } from "./client.js";
+export { IdReader } from "./reader.js";
+export { isCanonicalName } from "./name.js";
 export * from "./errors.js";
 export { HttpError } from "./http.js";
 export { REPORT_BODY_LIMIT, REPORT_CIPHERTEXT_LIMIT, REPORT_TEXT_MAX, } from "./report.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,oBAAoB,EACpB,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,GAEhB,MAAM,iBAAiB,CAAC;AAMzB,OAAO,EAAE,QAAQ,EAAwB,MAAM,aAAa,CAAC;AAC7D,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AA6BtC,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,eAAe,GAIhB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAe,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,uBAAuB,EACvB,oBAAoB,EACpB,YAAY,EACZ,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,GAEhB,MAAM,iBAAiB,CAAC;AAMzB,OAAO,EAAE,QAAQ,EAAwB,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,QAAQ,EAAwB,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AA6BtC,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,eAAe,GAIhB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAe,MAAM,aAAa,CAAC"}

package/dist/reader.d.ts

@@ -0,0 +1,24 @@
+import { type IdNetwork } from "./networks.js";
+import { type Availability, type AvailabilityReadOptions, type IdentityDocument, type OwnerLinks, type PropertyClaimedResult, type PropertyClaimKind, type ResolvedId } from "./reads.js";
+export interface IdReaderOptions {
+    network: IdNetwork;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Signer-free access to the public Fast ID reads.
+ *
+ * Use this when you only need to look identities up (for example, resolving
+ * `alice.smith` to its `fast1…` address before a transfer). It performs the
+ * same response validation as {@link IdClient}, including the network and
+ * name-binding checks, but needs no key material.
+ */
+export declare class IdReader {
+    #private;
+    constructor(options: IdReaderOptions);
+    resolve(identity: string): Promise<ResolvedId>;
+    identity(address: string): Promise<IdentityDocument>;
+    availability(name: string, options?: AvailabilityReadOptions): Promise<Availability>;
+    links(address: string): Promise<OwnerLinks>;
+    propertyClaimed(kind: PropertyClaimKind, value: string): Promise<PropertyClaimedResult>;
+}
+//# sourceMappingURL=reader.d.ts.map

package/dist/reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../src/reader.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAC3D,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,qBAAqB,EAC1B,KAAK,iBAAiB,EACtB,KAAK,UAAU,EAChB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,SAAS,CAAC;IACnB,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,qBAAa,QAAQ;;gBAGP,OAAO,EAAE,eAAe;IAMpC,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAI9C,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAIpD,YAAY,CACV,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE,uBAAuB,GAChC,OAAO,CAAC,YAAY,CAAC;IAIxB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAI3C,eAAe,CACb,IAAI,EAAE,iBAAiB,EACvB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,qBAAqB,CAAC;CAGlC"}

package/dist/reader.js

@@ -0,0 +1,35 @@
+import { HttpClient } from "./http.js";
+import { networkFor } from "./networks.js";
+import { IdReads, } from "./reads.js";
+/**
+ * Signer-free access to the public Fast ID reads.
+ *
+ * Use this when you only need to look identities up (for example, resolving
+ * `alice.smith` to its `fast1…` address before a transfer). It performs the
+ * same response validation as {@link IdClient}, including the network and
+ * name-binding checks, but needs no key material.
+ */
+export class IdReader {
+    #reads;
+    constructor(options) {
+        const config = networkFor(options.network);
+        const http = new HttpClient(config.idOrigin, options.fetchImpl ?? fetch);
+        this.#reads = new IdReads(http, config.networkId);
+    }
+    resolve(identity) {
+        return this.#reads.resolve(identity);
+    }
+    identity(address) {
+        return this.#reads.identity(address);
+    }
+    availability(name, options) {
+        return this.#reads.availability(name, options);
+    }
+    links(address) {
+        return this.#reads.links(address);
+    }
+    propertyClaimed(kind, value) {
+        return this.#reads.propertyClaimed(kind, value);
+    }
+}
+//# sourceMappingURL=reader.js.map

package/dist/reader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reader.js","sourceRoot":"","sources":["../src/reader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,UAAU,EAAkB,MAAM,eAAe,CAAC;AAC3D,OAAO,EACL,OAAO,GAQR,MAAM,YAAY,CAAC;AAOpB;;;;;;;GAOG;AACH,MAAM,OAAO,QAAQ;IACV,MAAM,CAAU;IAEzB,YAAY,OAAwB;QAClC,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC3C,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,SAAS,IAAI,KAAK,CAAC,CAAC;QACzE,IAAI,CAAC,MAAM,GAAG,IAAI,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;IAED,OAAO,CAAC,QAAgB;QACtB,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED,QAAQ,CAAC,OAAe;QACtB,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACvC,CAAC;IAED,YAAY,CACV,IAAY,EACZ,OAAiC;QAEjC,OAAO,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACjD,CAAC;IAED,KAAK,CAAC,OAAe;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC;IAED,eAAe,CACb,IAAuB,EACvB,KAAa;QAEb,OAAO,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAClD,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastxyz/fastid-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Programmatic client for id.fast.xyz — everything a non-admin user can do, for agents",
   "license": "Apache-2.0",
   "repository": {