@sage-protocol/sdk 0.1.21 → 0.1.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sage-protocol/sdk",
-  "version": "0.1.21",
+  "version": "0.1.24",
   "description": "Backend-agnostic SDK for interacting with the Sage Protocol (governance, SubDAOs, tokens).",
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",

package/types/index.d.ts

@@ -140,6 +140,42 @@ export interface VotesTokenDescription {
   description: string;
 }
 
+// ============ Governance Profile Types (3-Axis Model) ============
+
+export type GovernanceKind = 'operator' | 'token';
+export type ProposalAccess = 'council-only' | 'community-threshold';
+export type ExecutionAccess = 'council-only' | 'anyone';
+export type GovernancePlaybook = 'council-closed' | 'council-drafts' | 'community' | 'legacy' | 'custom';
+
+export interface GovernanceProfile {
+  /** Profile version: 1=legacy (detected via heuristics), 2=explicit 3-axis profile */
+  version: 1 | 2;
+  /** OPERATOR (council/EOA decides) or TOKEN (ERC20Votes snapshot) */
+  governanceKind: GovernanceKind | null;
+  /** COUNCIL_ONLY (only COUNCIL_ROLE) or COMMUNITY_THRESHOLD (token holders >= threshold) */
+  proposalAccess: ProposalAccess | null;
+  /** COUNCIL_ONLY (only council can execute) or ANYONE (public execution) */
+  executionAccess: ExecutionAccess | null;
+  /** Derived playbook name for UX */
+  playbook: GovernancePlaybook;
+  /** True if proposals require COUNCIL_ROLE */
+  isCouncil: boolean;
+  /** True if SXXX stake is required to propose (TOKEN + COMMUNITY_THRESHOLD only) */
+  requiresStake: boolean;
+}
+
+export interface GovernanceModeDetectionResult extends GovernanceProfile {
+  /** Legacy operator flag */
+  operator: boolean;
+  /** Legacy governance mode label */
+  governance: string;
+  governor: AddressLike | null;
+  timelock: AddressLike | null;
+  subdao: AddressLike | null;
+  stakeRequired: bigint | null;
+  depositWei: bigint | null;
+}
+
 export interface VotingStatus {
   subdao: AddressLike | null;
   governor: AddressLike;
@@ -163,7 +199,13 @@ export interface VotingStatus {
 
 export interface ProposeGatesSummary {
   threshold: bigint | null;
-  cooldown: bigint | null;
+  sxxxBalance: bigint | null;
+  thresholdMet: boolean | null;
+  cooldownRemaining: bigint | null;
+  cooldownElapsed: boolean | null;
+  canPropose: boolean | null;
+  votingPower: bigint | null;
+  votesTimepoint: bigint | null;
   stake: bigint | null;
   allowanceOk: boolean | null;
   votesOk: boolean | null;
@@ -172,6 +214,8 @@ export interface ProposeGatesSummary {
     proposer: AddressLike;
     governor: AddressLike;
   };
+  /** Alias of cooldownRemaining (legacy) */
+  cooldown: bigint | null;
 }
 
 export interface ProposeReadiness extends ProposeGatesSummary {
@@ -189,6 +233,9 @@ export interface GovernanceModule {
     proposalThreshold: bigint | null;
     timelock: AddressLike | null;
     sxxxToken: AddressLike | null;
+    /** Fixed quorum as absolute vote count (e.g., 100e18 = 100 SXXX) */
+    quorumVotes: bigint | null;
+    /** @deprecated Use quorumVotes instead */
     quorumNumerator: bigint | null;
     stakeAmount: bigint | null;
   }>;
@@ -240,7 +287,10 @@ export interface GovernanceModule {
   }): Promise<any>;
   getQuorumAt(args: { provider: ProviderLike; governor: AddressLike; blockTag?: bigint | number | string }): Promise<bigint | null>;
   getQuorumLatestMinusOne(args: { provider: ProviderLike; governor: AddressLike }): Promise<bigint | null>;
+  getVotesTimepointLatestMinusOne(args: { provider: ProviderLike }): Promise<bigint>;
+  getVotesAtTimepoint(args: { provider: ProviderLike; token?: AddressLike; governor?: AddressLike; account: AddressLike; timepoint: bigint | number | string }): Promise<bigint>;
   getVotesLatestMinusOne(args: { provider: ProviderLike; token?: AddressLike; governor?: AddressLike; account: AddressLike }): Promise<bigint>;
+  getVotesLatestMinusOneWithTimepoint(args: { provider: ProviderLike; token?: AddressLike; governor?: AddressLike; account: AddressLike }): Promise<{ votes: bigint; timepoint: bigint }>;
   simulatePropose(args: {
     provider: ProviderLike;
     governor: AddressLike;
@@ -269,6 +319,20 @@ export interface GovernanceModule {
     signer?: any;
     minVotes?: bigint | number | string | null;
   }): Promise<{ txHash: string | null; ok: boolean; votes: bigint; payload: TransactionPayload }>;
+  getProposalThresholdStatus(args: { provider: ProviderLike; governor: AddressLike; proposer: AddressLike }): Promise<{
+    governor: AddressLike;
+    proposer: AddressLike;
+    proposalThreshold: bigint | null;
+    sxxxToken: AddressLike | null;
+    sxxxBalance: bigint | null;
+    proposerVotes: bigint | null;
+    votesTimepoint: bigint | null;
+    thresholdMet: boolean | null;
+    cooldownRemaining: bigint | null;
+    cooldownElapsed: boolean | null;
+    canPropose: boolean;
+  }>;
+  getProposalCancelability(args: { provider: ProviderLike; governor: AddressLike; proposalId: bigint | number | string }): Promise<any>;
   ensureProposeGates(args: { provider: ProviderLike; governor: AddressLike; proposer: AddressLike }): Promise<ProposeGatesSummary>;
   readinessToPropose(args: {
     provider: ProviderLike;
@@ -284,6 +348,18 @@ export interface GovernanceModule {
       promptCount?: bigint | number | string;
     } | null;
   }): Promise<ProposeReadiness>;
+  getAuthorityAndReadiness(args: {
+    provider: ProviderLike;
+    subdao?: AddressLike | null;
+    governor?: AddressLike | null;
+    account?: AddressLike | null;
+    action: 'propose' | 'vote' | 'queue' | 'execute' | 'timelock-schedule' | 'update-library';
+    proposalId?: bigint | number | string | null;
+    libraryRegistry?: AddressLike | null;
+    dao?: AddressLike | null;
+    manifestCID?: string | null;
+    version?: string | null;
+  }): Promise<any>;
   listActiveProposals(args: { url: string; governor: AddressLike; first?: number; skip?: number }): Promise<any>;
   buildProposeTxByHash(args: {
     governor: AddressLike;
@@ -292,15 +368,7 @@ export interface GovernanceModule {
     calldatas?: string[];
     descriptionHash: string;
   }): TransactionPayload;
-  detectMode(args: { provider: ProviderLike; governor?: AddressLike; timelock?: AddressLike | null; subdao?: AddressLike | null }): Promise<{
-    operator: boolean;
-    governance: string;
-    governor: AddressLike | null;
-    timelock: AddressLike | null;
-    subdao: AddressLike | null;
-    stakeRequired: bigint | null;
-    depositWei: bigint | null;
-  }>;
+  detectMode(args: { provider: ProviderLike; governor?: AddressLike; timelock?: AddressLike | null; subdao?: AddressLike | null }): Promise<GovernanceModeDetectionResult>;
   [key: string]: any;
 }
 
@@ -341,6 +409,13 @@ export interface IpfsClient {
     warm?: boolean;
     gateways?: string[] | string;
   }): Promise<IpfsUploadResult>;
+  uploadRawJson(content: object, options?: {
+    name?: string;
+    providers?: string[] | string;
+    provider?: string;
+    warm?: boolean;
+    gateways?: string[] | string;
+  }): Promise<IpfsUploadResult>;
   downloadJson(args: { cid: string; gateways?: string[] | string; headers?: Record<string, string> }): Promise<any>;
   warmGateways(cid: string, options?: { gateways?: string[] | string; timeoutMs?: number; concurrency?: number }): Promise<{ warmed: string[] }>;
   buildGatewayUrls(cid: string, extra?: string[] | string): string[];
@@ -371,6 +446,7 @@ export interface IpfsModule {
     pinataSecretKey?: string;
     pinataJwt?: string;
     workerUploadUrl?: string;
+    workerUploadRawPath?: string;
     workerUploadToken?: string;
     workerBaseUrl?: string;
     workerAddress?: string;
@@ -499,13 +575,13 @@ export interface LibrarySearchResponse {
 }
 
 export interface LibraryModule {
-  listManifests(args: { provider: ProviderLike; registry: AddressLike; offset?: number; limit?: number }): Promise<{ total: bigint; manifests: Array<{ manifestCID: string; previousCID: string; timestamp: bigint; proposer: AddressLike; promptCount: number; }> }>;
-  getManifestInfo(args: { provider: ProviderLike; registry: AddressLike; manifestCID: string }): Promise<{ manifestCID: string; previousCID: string; timestamp: bigint; proposer: AddressLike; promptCount: number; }>;
-  getLatestLibrary(args: { provider: ProviderLike; registry: AddressLike; subdao: AddressLike; libraryId?: string }): Promise<{ manifestCID: string; previousCID: string; timestamp: bigint; proposer: AddressLike; promptCount: number; } | null>;
+  listManifests(args: { provider: ProviderLike; registry: AddressLike; factoryAddress: AddressLike; offset?: number; limit?: number }): Promise<{ total: bigint; manifests: Array<{ manifestCID: string; previousCID: string; timestamp: bigint; proposer: AddressLike; promptCount: number; version: string; }> }>;
+  getManifestInfo(args: { provider: ProviderLike; registry: AddressLike; manifestCID: string }): Promise<never>;
+  getLatestLibrary(args: { provider: ProviderLike; registry: AddressLike; subdao: AddressLike }): Promise<{ manifestCID: string; previousCID: string; timestamp: bigint; proposer: AddressLike; promptCount: number; version: string; } | null>;
   hasScopedOwnership(args: { provider: ProviderLike; registry: AddressLike; subdao: AddressLike; manifestCID: string }): Promise<boolean>;
-  buildUpdateLibraryForSubDAOTx(args: { registry: AddressLike; subdao: AddressLike; manifestCID: string; promptCount?: bigint | number | string; libraryId?: string }): TransactionPayload;
+  buildUpdateLibraryTx(args: { registry: AddressLike; subdao: AddressLike; manifestCID: string; version?: string }): TransactionPayload;
   buildAuthorizeTimelockTx(args: { registry: AddressLike; timelock: AddressLike; subdao: AddressLike }): TransactionPayload;
-  executionReadiness(args: { provider: ProviderLike; registry: AddressLike; timelock: AddressLike; subdao: AddressLike; libraryId?: string; manifestCID?: string; promptCount?: bigint | number | string }): Promise<{ ok: boolean; error: string | null; missingRole: string | null }>;
+  executionReadiness(args: { provider: ProviderLike; registry: AddressLike; timelock: AddressLike; subdao: AddressLike; manifestCID?: string; version?: string }): Promise<{ ok: boolean; error: string | null; missingRole: string | null }>;
   searchRegistry(args: { provider: ProviderLike; registry: AddressLike; query: string; limit?: number; ipfsClient?: any; ipfsOptions?: Record<string, any>; libraryAdapter?: any; manifestFetcher?: (cid: string) => Promise<any>; }): Promise<LibrarySearchResponse>;
   validation: { createManifestValidator(options?: Record<string, any>): ManifestValidator };
 }
@@ -858,6 +934,122 @@ export interface BountySubmission {
   exists: boolean;
 }
 
+// ---- Contributions Module ----
+
+export type GovernanceModel = 'TOKEN_VOTING' | 'COUNCIL' | 'OPERATOR' | 'DIRECT';
+
+export interface PromptContribution {
+  id: string;
+  dao: AddressLike;
+  daoName: string | null;
+  promptKey: string;
+  contributor: AddressLike;
+  cid: string;
+  timestamp: number;
+  createdAt: number;
+  updatedAt: number;
+  transactionHash: string | null;
+  governanceModel: GovernanceModel;
+  proposalId: bigint | null;
+  forVotes: bigint | null;
+  againstVotes: bigint | null;
+  abstainVotes: bigint | null;
+  uniqueVoters: number | null;
+  quorum: bigint | null;
+  fromBounty: boolean;
+  bountyId: bigint | null;
+  badgeId: bigint | null;
+  badgeEvidenceURI: string | null;
+}
+
+export interface ContributionAggregates {
+  totalContributions: number;
+  uniqueContributors: number;
+  bountyOriginated: number;
+  governanceOriginated: number;
+  totalForVotes: bigint;
+  totalAgainstVotes: bigint;
+  averageVoterCount: number;
+  badgeCount: number;
+}
+
+export interface GovernanceQuality {
+  model: GovernanceModel;
+  decentralization: number;
+  consensus: number;
+  raw: Record<string, any>;
+}
+
+export interface SoulboundBadge {
+  id: string;
+  contract: AddressLike;
+  badgeId: bigint;
+  recipient: AddressLike;
+  evidenceURI: string | null;
+  blockNumber: number;
+  blockTimestamp: number;
+  transactionHash: string | null;
+}
+
+export interface ContributionsModule {
+  GovernanceModel: {
+    TOKEN_VOTING: 'TOKEN_VOTING';
+    COUNCIL: 'COUNCIL';
+    OPERATOR: 'OPERATOR';
+    DIRECT: 'DIRECT';
+  };
+
+  listContributions(args: {
+    url: string;
+    subdao?: AddressLike;
+    promptKey?: string;
+    contributor?: AddressLike;
+    fromBounty?: boolean;
+    first?: number;
+    skip?: number;
+    orderBy?: 'updatedAt' | 'createdAt';
+    orderDirection?: 'asc' | 'desc';
+  }): Promise<PromptContribution[]>;
+
+  getByPrompt(args: {
+    url: string;
+    subdao: AddressLike;
+    promptKey: string;
+  }): Promise<{ contributions: PromptContribution[]; aggregates: ContributionAggregates }>;
+
+  getById(args: {
+    url: string;
+    id: string;
+  }): Promise<PromptContribution | null>;
+
+  getByContributor(args: {
+    url: string;
+    contributor: AddressLike;
+    first?: number;
+    skip?: number;
+  }): Promise<PromptContribution[]>;
+
+  getBadgesByRecipient(args: {
+    url: string;
+    recipient: AddressLike;
+    first?: number;
+  }): Promise<SoulboundBadge[]>;
+
+  getGovernanceQuality(
+    contribution: PromptContribution,
+    context?: { totalHolders?: number; totalCouncilMembers?: number }
+  ): GovernanceQuality;
+
+  enrichWithGovernanceModel(
+    contribution: PromptContribution,
+    subdaoInfo: any
+  ): PromptContribution;
+
+  detectGovernanceModel(subdaoInfo: any): GovernanceModel;
+
+  computeAggregates(contributions: PromptContribution[]): ContributionAggregates;
+}
+
 export interface BountyModule {
   // Constants
   getMaxSubmissionsPerBounty(args: { provider: ProviderLike; bountySystem: AddressLike }): Promise<bigint>;
@@ -926,6 +1118,220 @@ export interface BountyModule {
   buildRemoveFromWhitelistTx(args: { bountySystem: AddressLike; bountyId: BigNumberish; addresses: AddressLike[] }): TransactionPayload;
 }
 
+// ============ Git Storage Client Types ============
+
+export type GitObjectType = 'blob' | 'tree' | 'commit';
+
+export interface GitObject {
+  /** Object ID (SHA-1 hash) */
+  oid: string;
+  /** Object type */
+  type: GitObjectType;
+  /** Object size in bytes */
+  size: number;
+  /** Base64 encoded object data */
+  data: string;
+}
+
+export interface GitRef {
+  /** Reference name (e.g., 'refs/heads/main') */
+  name: string;
+  /** Object ID the ref points to */
+  oid: string;
+  /** Last update timestamp */
+  updatedAt: number;
+  /** Wallet address of last updater */
+  updatedBy?: string;
+}
+
+export interface GitCommit {
+  /** Commit hash */
+  oid: string;
+  /** Tree object hash */
+  treeOid: string;
+  /** Parent commit hash */
+  parentOid?: string;
+  /** Commit message */
+  message: string;
+  /** Author name */
+  authorName?: string;
+  /** Author email */
+  authorEmail?: string;
+  /** Author wallet address */
+  authorAddress?: string;
+  /** Commit timestamp */
+  timestamp: number;
+}
+
+export interface LibraryMetadata {
+  /** SubDAO address */
+  subdao: string;
+  /** Library name */
+  name: string;
+  /** Library description */
+  description?: string;
+  /** Library visibility */
+  visibility: 'public' | 'private';
+  /** Creation timestamp */
+  createdAt: number;
+  /** Last update timestamp */
+  updatedAt: number;
+  /** Fork information */
+  forkOf?: {
+    subdao: string;
+    commit: string;
+  };
+}
+
+export interface Collaborator {
+  /** Wallet address */
+  address: string;
+  /** Permission level */
+  permission: 'read' | 'write' | 'admin';
+  /** When collaborator was added */
+  addedAt: number;
+  /** Who added the collaborator */
+  addedBy?: string;
+}
+
+export interface PushResult {
+  /** Whether push succeeded */
+  success: boolean;
+  /** New commit hash */
+  commitHash?: string;
+  /** Error message if failed */
+  error?: string;
+}
+
+export interface PushPayload {
+  /** Objects to push */
+  objects: GitObject[];
+  /** Ref updates (name -> oid) */
+  refs: Record<string, string>;
+  /** Commit message */
+  message: string;
+}
+
+export interface CloneResult {
+  /** All objects in the library */
+  objects: GitObject[];
+  /** All refs (name -> oid) */
+  refs: Record<string, string>;
+  /** Library metadata */
+  metadata: LibraryMetadata;
+}
+
+export interface FetchResult {
+  /** Objects since the given commit */
+  objects: GitObject[];
+  /** Current refs (name -> oid) */
+  refs: Record<string, string>;
+}
+
+export interface CollaboratorPermissions {
+  canRead: boolean;
+  canWrite: boolean;
+  isAdmin: boolean;
+  permission?: string;
+}
+
+export interface GitAuthProvider {
+  /** Get wallet address */
+  getAddress(): Promise<string>;
+  /** Sign a message */
+  signMessage(message: string): Promise<string>;
+}
+
+export interface GitStorageClientOptions {
+  /** Request timeout in milliseconds (default: 30000) */
+  timeout?: number;
+  /** Custom headers */
+  headers?: Record<string, string>;
+  /** Ethers signer for authenticated requests */
+  signer?: GitAuthProvider | (() => Promise<GitAuthProvider>);
+  /** Custom auth provider */
+  getAuth?: () => Promise<{ address: string; signature: string; nonce: string }>;
+  /** Bearer token for authentication */
+  token?: string;
+}
+
+export interface GitStorageClient {
+  readonly baseUrl: string;
+  readonly timeout: number;
+  readonly headers: Record<string, string>;
+
+  // Library Management
+  createLibrary(subdao: string, name: string, options?: {
+    description?: string;
+    visibility?: 'public' | 'private';
+  }): Promise<LibraryMetadata>;
+
+  getLibrary(subdao: string): Promise<LibraryMetadata>;
+
+  listLibraries(options?: {
+    limit?: number;
+    cursor?: string;
+  }): Promise<{ libraries: LibraryMetadata[]; cursor?: string }>;
+
+  deleteLibrary(subdao: string): Promise<{ ok: boolean }>;
+
+  // Git Object Operations
+  putObjects(subdao: string, objects: GitObject[]): Promise<{ stored: number }>;
+  getObject(subdao: string, oid: string): Promise<GitObject>;
+  getObjects(subdao: string, oids: string[]): Promise<{ objects: GitObject[] }>;
+
+  // Reference Operations
+  listRefs(subdao: string): Promise<{ refs: GitRef[] }>;
+  getRef(subdao: string, refName: string): Promise<GitRef>;
+  updateRef(subdao: string, refName: string, oid: string, options?: {
+    oldOid?: string;
+  }): Promise<{ ok: boolean }>;
+
+  // Sync Operations
+  push(subdao: string, payload: PushPayload): Promise<PushResult>;
+  clone(subdao: string): Promise<CloneResult>;
+  fetch(subdao: string, since?: string): Promise<FetchResult>;
+
+  // File Access
+  getHistory(subdao: string, options?: {
+    ref?: string;
+    limit?: number;
+  }): Promise<{ commits: GitCommit[] }>;
+
+  getTree(subdao: string, ref: string, path: string): Promise<{ entries: Array<{
+    name: string;
+    type: 'blob' | 'tree';
+    oid: string;
+  }> }>;
+
+  getBlob(subdao: string, ref: string, path: string): Promise<{ content: string }>;
+  getFile(subdao: string, ref: string, path: string): Promise<string>;
+
+  // Fork Operations
+  fork(sourceSubdao: string, targetSubdao: string): Promise<{ success: boolean; commitHash?: string }>;
+  getForks(subdao: string): Promise<{ forks: Array<{ subdao: string; forkedAt: number }> }>;
+  getUpstream(subdao: string): Promise<{ upstreamSubdao: string; upstreamCommit: string; forkedAt: number }>;
+
+  // Collaborator Operations
+  listCollaborators(subdao: string): Promise<{ collaborators: Collaborator[] }>;
+  addCollaborator(subdao: string, address: string, permission: 'read' | 'write' | 'admin'): Promise<{ ok: boolean }>;
+  removeCollaborator(subdao: string, address: string): Promise<{ ok: boolean }>;
+  getPermissions(subdao: string, address: string): Promise<CollaboratorPermissions>;
+
+  // High-Level Convenience Methods
+  pushManifest(subdao: string, manifest: object, message: string): Promise<PushResult>;
+  getManifest(subdao: string, ref?: string): Promise<object>;
+
+  // Cache Management
+  clearAuthCache(): void;
+}
+
+export interface GitStorageClientConstructor {
+  new (baseUrl: string, options?: GitStorageClientOptions): GitStorageClient;
+}
+
+export declare const GitStorageClient: GitStorageClientConstructor;
+
 export interface SageSDK {
   version: string;
   getProvider: (rpcUrl: string) => any;
@@ -959,9 +1365,17 @@ export interface SageSDK {
   votingMultiplier: VotingMultiplierModule;
   auction: AuctionModule;
   bounty: BountyModule;
+  contributions: ContributionsModule;
   subgraph: Record<string, any>;
   errors: Record<string, any>;
   resolveGovernanceContext: (args: any) => Promise<any>;
+  // Client exports
+  clients: {
+    DiscoveryClient: any;
+    GitStorageClient: GitStorageClientConstructor;
+  };
+  DiscoveryClient: any;
+  GitStorageClient: GitStorageClientConstructor;
 }
 
 declare const sdk: SageSDK;