@iqlabs-official/git-sdk 0.1.12 → 0.1.15

package/dist/shared/index.d.ts

@@ -1,6 +1,7 @@
 import { SessionSpeedOption, SignerInput } from '@iqlabs-official/solana-sdk/utils';
 export { DEFAULT_SESSION_SPEED, SESSION_SPEED_PROFILES, SignerInput, resolveSessionSpeed } from '@iqlabs-official/solana-sdk/utils';
-import { Connection, PublicKey } from '@solana/web3.js';
+import { Connection } from '@solana/web3.js';
+import { Signer } from 'ethers';
 
 /** Metadata row stored in `git_repos_v2_<owner>`. */
 interface Repository {
@@ -30,6 +31,30 @@ interface RegistryEntry {
     description: string;
     timestamp: number;
 }
+/** Deploy marker row stored in the `iqpages-root/deployed` gallery table. */
+interface PagesDeployment {
+    id: string;
+    owner: string;
+    repo: string;
+    deployedAt: number;
+}
+/** `iqpages.json` — the deploy manifest a repo commits at its root. */
+interface PagesConfig {
+    name: string;
+    version: string;
+    description: string;
+    entry: string;
+}
+/** `iqprofile.json` — optional profile/routing metadata for a deployed site. */
+interface PagesProfile {
+    displayName: string;
+    description: string;
+    icon?: string;
+    routes?: {
+        profile?: string;
+        myPage?: string;
+    };
+}
 
 /** DbRoot id for every iq-git table. Bootstrap and every caller share this. */
 declare const IQGIT_ROOT_ID = "iq-git-v1";
@@ -47,17 +72,49 @@ declare function repoListHint(owner: string): string;
  * output: "git_commits:<owner>:<repo>"
  */
 declare function commitTableHint(owner: string, repo: string): string;
-
+/** DbRoot id for the iq-pages deployment gallery. */
+declare const IQPAGES_ROOT_ID = "iqpages-root";
+/** Single open-writers table that holds every deploy marker row. */
+declare const IQPAGES_DEPLOYED_HINT = "deployed";
+/** One-time deploy fee on Solana, in lamports (0.2 SOL). */
+declare const PAGES_FEE_LAMPORTS = 200000000;
+/** One-time deploy fee on EVM, in wei (0.01 ETH — value-matched to 0.2 SOL). */
+declare const PAGES_FEE_WEI = 10000000000000000n;
+/** Receiver of the Solana deploy fee. Same hard receiver the contract uses. */
+declare const PAGES_FEE_RECIPIENT = "EWNSTD8tikwqHMcRNuuNbZrnYJUiJdKq9UXLXSEU4wZ1";
+/** Receiver of the EVM deploy fee — the same address the ethereum-sdk's
+ *  on-chain `feeReceiver()` resolves to across sepolia / monad / monadTestnet
+ *  (verified identical on all three). Pages fee is an app-layer transfer
+ *  outside the contract, so we send it to the protocol's fee wallet directly. */
+declare const PAGES_FEE_RECIPIENT_EVM = "0xE94fA75aB69C18635A35556E9313e8D2aE009459";
+/** Config / profile filenames a repo must commit to be deployable. */
+declare const IQPAGES_CONFIG_FILENAME = "iqpages.json";
+declare const IQPAGES_PROFILE_FILENAME = "iqprofile.json";
 /**
- * Speed forwarded to `iqlabs.writer.codeIn`. Either a preset name
- * (`"light" | "medium" | "heavy" | "extreme"`) or a raw override object —
- * `{ maxRps?, maxConcurrency?, maxConcurrencyUpload? }` — when you want to
- * dial RPS / concurrency directly without picking a preset.
- *
- * Re-exported here so consumers don't have to import both SDKs to pick a
- * value. See solana-sdk's `SessionSpeedOption` for the full type.
+ * Deploy-marker row id.
+ * input:  owner wallet address, repo name
+ * output: "<owner>:<repo>"
  */
+declare function pagesDeployId(owner: string, repo: string): string;
+
+/** Re-exported solana-sdk speed dial — preset name or raw RPS/concurrency
+ *  override. EVM ignores it (no client-side chunk pacing on that path). */
 type SessionSpeed = SessionSpeedOption;
+/**
+ * Opaque handle to a table. Solana resolves a hint to a `PublicKey` PDA; EVM
+ * resolves it to `{ dbRootId, tableName }`. Callers above L1 treat it as a
+ * black box and only ever hand it back to `readRowsByRef`.
+ */
+type TableRef = unknown;
+/**
+ * A signer accepted by the active chain. The Solana adapter narrows to
+ * `SignerInput` (Keypair / wallet adapter); the EVM adapter narrows to an
+ * ethers `Signer`. Kept as a union here so one `ChainOps` interface can be
+ * satisfied by both — Phase 2 threads this through the client surface.
+ */
+type GitSigner = SignerInput | Signer;
+/** EVM sub-networks the eth adapter understands (mirrors ethereum-sdk). */
+type EthNetwork = "sepolia" | "monad" | "monadTestnet";
 
 /** Information surfaced to the `onWrite` callback for every successful row
  *  write the SDK performs. Consumers wire this to their gateway notify so
@@ -72,19 +129,37 @@ interface WriteEvent {
     /** The row object that was written (already JSON.stringify-able). */
     row: object;
 }
-interface GitClientConfig {
-    connection: Connection;
-    signer: SignerInput;
+/** Fields common to every chain's client config. */
+interface BaseClientConfig {
     /** Fires after each successful row write inside the SDK. Fire-and-forget
      *  callback for gateway notifies; throwing here will surface to the caller. */
     onWrite?: (event: WriteEvent) => void;
-    /** Default solana-sdk session speed for blob / tree uploads (`"light"` is
-     *  the per-operation default and works well on Helius free-tier RPCs).
-     *  Override per call with `commit({ speed })`. See `SESSION_SPEED_PROFILES`. */
+    /** Default session speed for blob / tree uploads (`"light"` is the per-op
+     *  default; Helius-friendly). EVM ignores it. Override per call with
+     *  `commit({ speed })`. See `SESSION_SPEED_PROFILES`. */
     speed?: SessionSpeed;
 }
+/** Solana client: a web3.js `Connection` + a Solana signer. `chain` is
+ *  optional and defaults to `'solana'` so existing callers keep working. */
+interface SolanaClientConfig extends BaseClientConfig {
+    chain?: "solana";
+    connection: Connection;
+    signer: SignerInput;
+}
+/** EVM client: an ethers `Signer` (carries its provider) + the target EVM
+ *  network. No `Connection`. */
+interface EthClientConfig extends BaseClientConfig {
+    chain: "eth";
+    signer: Signer;
+    network: EthNetwork;
+    /** Optional RPC override; defaults to the network's public endpoint. */
+    rpcUrl?: string;
+}
+type GitClientConfig = SolanaClientConfig | EthClientConfig;
 declare class GitClient {
     private readonly cfg;
+    /** The configured signer, as the chain-neutral union the layers consume. */
+    private readonly signer;
     constructor(cfg: GitClientConfig);
     /**
      * Create a new repo. Wraps repo.createRepo + pre-creating the commit table
@@ -134,13 +209,13 @@ declare class GitClient {
 }
 
 /** List all repos owned by `owner`. */
-declare function readOwnerRepos(_connection: Connection, owner: string): Promise<Repository[]>;
+declare function readOwnerRepos(owner: string): Promise<Repository[]>;
 /**
  * One page of the public-gallery registry. Callers should still check
  * `row.owner` shape before trusting it in UI; we do not filter at the SDK
  * boundary.
  */
-declare function readRegistryPage(_connection: Connection, options?: {
+declare function readRegistryPage(options?: {
     limit?: number;
     before?: string;
 }): Promise<RegistryEntry[]>;
@@ -149,7 +224,7 @@ declare function readRegistryPage(_connection: Connection, options?: {
  * network from an admin key; subsequent calls short-circuit because the
  * account already exists.
  */
-declare function bootstrapRegistry(connection: Connection, signer: SignerInput): Promise<string | null>;
+declare function bootstrapRegistry(signer: GitSigner): Promise<string | null>;
 
 /**
  * Append one commit row. Callers (workflow-level code) are responsible for
@@ -159,15 +234,15 @@ declare function bootstrapRegistry(connection: Connection, signer: SignerInput):
  * iq-gateway already caching this table prepends the new commit without
  * waiting for RPC sig indexing.
  */
-declare function writeCommit(connection: Connection, signer: SignerInput, repo: string, commit: Commit): Promise<string>;
-/** The commit-table PDA for a repo. The one place owner/repo collapses to a
- *  PDA — every read keys off the PDA, so callers that have a PDA already (a
- *  .sol record, a dbroot match) skip this and pass it straight in. */
-declare function commitTablePda(owner: string, repo: string): PublicKey;
-/** Latest commit. Single-row, O(1) RPC path. */
-declare function readLatestCommit(pda: PublicKey): Promise<Commit | null>;
+declare function writeCommit(signer: GitSigner, repo: string, commit: Commit): Promise<string>;
+/** The commit-table reference for a repo. The one place owner/repo collapses
+ *  to a chain handle — every read keys off it, so callers that already have a
+ *  ref (a .sol record, a dbroot match) skip this and pass it straight in. */
+declare function commitTableRef(owner: string, repo: string): TableRef;
+/** Latest commit. Single-row, O(1) read path. */
+declare function readLatestCommit(ref: TableRef): Promise<Commit | null>;
 /** Full commit history, newest first. */
-declare function readCommitHistory(pda: PublicKey, options?: {
+declare function readCommitHistory(ref: TableRef, options?: {
     limit?: number;
     before?: string;
 }): Promise<Commit[]>;
@@ -178,14 +253,14 @@ declare function readCommitHistory(pda: PublicKey, options?: {
  * input:  connection, signer, relativePath, base64 content, reuse map, optional onProgress
  * output: { txId, hash } — either reused or freshly uploaded
  */
-declare function uploadBlob(connection: Connection, signer: SignerInput, relativePath: string, base64Content: string, reuse: FileTree, onProgress?: (percent: number) => void, speed?: SessionSpeed): Promise<{
+declare function uploadBlob(signer: GitSigner, relativePath: string, base64Content: string, reuse: FileTree, onProgress?: (percent: number) => void, speed?: SessionSpeed): Promise<{
     txId: string;
     hash: string;
 }>;
 /**
  * Serialize a FileTree and upload it as one `tree.json` blob.
  */
-declare function uploadTree(connection: Connection, signer: SignerInput, tree: FileTree, speed?: SessionSpeed): Promise<string>;
+declare function uploadTree(signer: GitSigner, tree: FileTree, speed?: SessionSpeed): Promise<string>;
 /**
  * Fetch and parse a `tree.json` blob by its tx signature.
  */
@@ -196,12 +271,55 @@ declare function loadTree(treeTxId: string): Promise<FileTree>;
  */
 declare function loadBlob(txId: string): Promise<string>;
 
+/** Ref to the single `iqpages-root/deployed` gallery table. Pages owns the
+ *  (root, hint) identity; the active adapter resolves it (Solana PDA / EVM
+ *  coordinates) — chain-neutral. */
+declare function pagesTableRef(): TableRef;
+/** Every deploy marker in the gallery. Gateway-first, RPC fallback (handled by
+ *  the adapter). */
+declare function listPagesDeployments(): Promise<PagesDeployment[]>;
+/** True if `<owner>/<repo>` already has a deploy marker. */
+declare function isPagesDeployed(owner: string, repo: string): Promise<boolean>;
+/** `iqpages.json` from the repo's latest commit, or null if not committed. */
+declare function readPagesConfig(owner: string, repo: string): Promise<PagesConfig | null>;
+/** `iqprofile.json` from the repo's latest commit, or null if not committed. */
+declare function readPagesProfile(owner: string, repo: string): Promise<PagesProfile | null>;
+/**
+ * Register `<owner>/<repo>` in the gallery and charge the one-time fee.
+ *
+ * Pre-flight (in order): not already deployed → `iqpages.json` is committed.
+ * Then it ensures the gallery exists, writes the marker row, and transfers the
+ * fee in a separate tx (the contract can't do both atomically).
+ *
+ * Returns the marker-row tx id plus the resolved config so callers can print
+ * the live site URL without a second read.
+ */
+declare function deployPages(signer: GitSigner, repo: string): Promise<{
+    sig: string;
+    config: PagesConfig;
+}>;
+
 /** Pin the gateway URL list explicitly. Highest precedence. Pass `[]` to
  *  disable gateway dispatch entirely (RPC-only mode). */
 declare function setGatewayUrls(urls: string[]): void;
-/** Pin the network label when the RPC URL doesn't reveal it (private nodes,
- *  proxies, etc.). Has no effect when setGatewayUrls() is also set. */
-declare function setNetwork(network: "mainnet" | "devnet"): void;
 declare function getGatewayUrls(): string[];
 
-export { type Commit, type FileTree, GitClient, type GitClientConfig, IQGIT_ROOT_ID, REGISTRY_HINT, type RegistryEntry, type Repository, type SessionSpeed, type WriteEvent, bootstrapRegistry, commitTableHint, commitTablePda, getGatewayUrls, loadBlob, loadTree, readCommitHistory, readLatestCommit, readOwnerRepos, readRegistryPage, repoListHint, setGatewayUrls, setNetwork, uploadBlob, uploadTree, writeCommit };
+type SolanaNetwork = "devnet" | "mainnet";
+/** Every token `setNetwork` accepts. `'eth'` ⇒ sepolia (EVM default). */
+type NetworkToken = SolanaNetwork | "eth" | EthNetwork;
+/**
+ * Switch the active chain + network from a single token.
+ *
+ *   setNetwork('mainnet')      // Solana mainnet
+ *   setNetwork('devnet')       // Solana devnet
+ *   setNetwork('eth')          // EVM, sepolia (default)
+ *   setNetwork('monad', { rpcUrl })   // EVM, monad, custom RPC
+ *
+ * `rpcUrl` only applies to EVM tokens (the EVM adapter holds the provider);
+ * Solana reads resolve their RPC from the gateway / `setRpcUrl`.
+ */
+declare function setNetwork(token: NetworkToken, options?: {
+    rpcUrl?: string;
+}): void;
+
+export { type Commit, type EthClientConfig, type EthNetwork, type FileTree, GitClient, type GitClientConfig, type GitSigner, IQGIT_ROOT_ID, IQPAGES_CONFIG_FILENAME, IQPAGES_DEPLOYED_HINT, IQPAGES_PROFILE_FILENAME, IQPAGES_ROOT_ID, type NetworkToken, PAGES_FEE_LAMPORTS, PAGES_FEE_RECIPIENT, PAGES_FEE_RECIPIENT_EVM, PAGES_FEE_WEI, type PagesConfig, type PagesDeployment, type PagesProfile, REGISTRY_HINT, type RegistryEntry, type Repository, type SessionSpeed, type SolanaClientConfig, type SolanaNetwork, type TableRef, type WriteEvent, bootstrapRegistry, commitTableHint, commitTableRef, deployPages, getGatewayUrls, isPagesDeployed, listPagesDeployments, loadBlob, loadTree, pagesDeployId, pagesTableRef, readCommitHistory, readLatestCommit, readOwnerRepos, readPagesConfig, readPagesProfile, readRegistryPage, repoListHint, setGatewayUrls, setNetwork, uploadBlob, uploadTree, writeCommit };