@sage-protocol/sdk 0.0.7 → 0.1.2

package/README.md

@@ -42,6 +42,15 @@ const info = await sdk.governance.getGovernorInfo({ provider, governor: subdaos[
 const sdk = require('@sage-protocol/sdk');
 ```
 
+What’s New in 0.0.8
+--------------------
+- 0.0.8 Highlights
+  - Governance helpers (additive): resolveVotesToken, buildDelegateSelfPreferred, delegateSelfAndVerify, ensureProposeGates, readinessToPropose, listActiveProposals
+  - Library helpers (additive): buildAuthorizeTimelockTx, executionReadiness
+  - Subgraph normalization: listProposalsFiltered returns state (string) and stateNum (0–7)
+  - Backward compatible: no removed/renamed exports; all additions are optional
+  - IPFS worker helpers: discovery signal APIs (`recordMcpUsage`, `recordLaunchEvent`, `recordDiscoveryEvent`) and governance queue actions (`submitGovernanceReport`, `listGovernanceReports`, `reviewGovernanceReport`, `batchGovernanceReports`)
+
 Module Overview
 ---------------
 
@@ -53,6 +62,7 @@ Module Overview
 | `factory` | Config reads, template enumeration, SubDAO create/fork builders | Launch tooling, analytics |
 | `library` | Manifest listings & scoped ownership checks | Prompt library browsers |
 | `prompt` | Prompt metadata, fork counts, usage counters | UI prompt catalogues, agent prompt selection |
+| `ipfs` | Upload helpers + discovery/governance worker APIs | CLI sandbox, dashboards, worker automation |
 | `subdao` | Discovery, staking helpers, per-user stats | SubDAO directories, onboarding |
 | `token` | SXXX balances/allowances, burner discovery, tx builders | Wallet gating, burner dashboards |
 | `treasury` | Reserve/POL snapshot, pending withdrawals, liquidity plans | Treasury analytics, Safe operators |
@@ -212,12 +222,111 @@ const tx = await sdk.governance.buildDelegateSelfTx({ provider, governor, accoun
 // send via userOp (CDP) or EOA
 ```
 
+Votes token resolution and gates
+```js
+// Resolve the IVotes token used for proposals
+const votesToken = await sdk.governance.resolveVotesToken({ provider, governor });
+
+// Build preferred self-delegate using resolved token
+const del = await sdk.governance.buildDelegateSelfPreferred({ provider, governor, account: user });
+
+// Delegate and verify votes (no throw)
+const res = await sdk.governance.delegateSelfAndVerify({ provider, governor, account: user, signer, minVotes: 1n });
+// → { txHash, ok, votes, payload }
+
+// Readiness to propose (preflight)
+const gates = await sdk.governance.ensureProposeGates({ provider, governor, proposer: user });
+// Optionally include execution check (registry update as timelock)
+const ready = await sdk.governance.readinessToPropose({
+  provider,
+  governor,
+  proposer: user,
+  execution: { registry, timelock, subdao, libraryId: 'main', manifestCID, promptCount: 12 },
+});
+```
+
+Subgraph normalization
+```js
+// listProposalsFiltered now returns both state (string) and stateNum (0–7)
+const items = await sdk.subgraph.listProposalsFiltered({ url: SUBGRAPH_URL, governor });
+// item.state → 'PENDING' | 'ACTIVE' | ... ; item.stateNum → 0..7 or null when unknown
+```
+
+Subgraph State Normalization
+----------------------------
+- State Mapping
+  - PENDING → 0
+  - ACTIVE → 1
+  - CANCELED/CANCELLED → 2
+  - DEFEATED → 3
+  - SUCCEEDED → 4
+  - QUEUED → 5
+  - EXPIRED → 6
+  - EXECUTED → 7
+- Example
+```js
+const items = await sdk.subgraph.listProposalsFiltered({ url: SUBGRAPH_URL, governor });
+console.log(items[0].state);    // 'PENDING'
+console.log(items[0].stateNum); // 0
+```
+
+New Helper Examples
+-------------------
+
+- Votes token + self‑delegate
+```js
+const votesToken = await sdk.governance.resolveVotesToken({ provider, governor });
+const tx = await sdk.governance.buildDelegateSelfPreferred({ provider, governor, account: user });
+const res = await sdk.governance.delegateSelfAndVerify({ provider, governor, account: user, signer, minVotes: 1n });
+console.log(res.ok, res.votes, res.txHash);
+```
+
+- Propose gates and execution readiness (one‑shot)
+```js
+const gates = await sdk.governance.ensureProposeGates({ provider, governor, proposer: user });
+const ready = await sdk.governance.readinessToPropose({
+  provider, governor, proposer: user,
+  execution: { registry, timelock, subdao, libraryId: 'main', manifestCID, promptCount: 12 }
+});
+console.log({ threshold: gates.threshold, votesOk: gates.votesOk, execReady: ready.executionReady });
+```
+
+- List active proposals (subgraph)
+```js
+const active = await sdk.governance.listActiveProposals({ url: SUBGRAPH_URL, governor });
+// active[i].state (string), active[i].stateNum (0–7)
+```
+
+- Library authorize + readiness
+```js
+const auth = sdk.library.buildAuthorizeTimelockTx({ registry, timelock, subdao });
+const exec = await sdk.library.executionReadiness({ provider, registry, timelock, subdao, libraryId: 'main', manifestCID, promptCount });
+console.log(exec.ok, exec.error);
+```
+
 Proposal timeline (subgraph)
 ```js
 const t = await sdk.subgraph.getProposalTimeline({ url: SUBGRAPH_URL, id: idHexOrDecimal });
 // { id, createdAt, queuedAt, executedAt, canceledAt, eta, state }
 ```
 
+Compatibility
+-------------
+- 0.0.8 Compatibility
+  - All changes are additive; no removed or renamed exports. Existing callers can continue to rely on string state. stateNum is optional.
+
+Troubleshooting
+---------------
+- JSON + BigInt
+  - Use a replacer when printing SDK results:
+```js
+JSON.stringify(obj, (_, v) => (typeof v === 'bigint' ? v.toString() : v));
+```
+- Governor filter casing
+  - The SDK normalizes governor for Bytes filters; if you issue manual GraphQL, use lowercase governor addresses to avoid case sensitivity pitfalls.
+- Votes snapshot timing
+  - getVotesLatestMinusOne reads at latest‑1 to avoid same‑block edge cases on ERC20Votes.
+
 Prompt pagination helpers
 ```js
 const totalByTag = await sdk.prompt.getByTagCount({ provider, registry, tagHash });