@poa-box/core 0.1.0

package/dist/reads/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Typed subgraph reads by domain. reads/resolve.ts (org resolution) is
+ * re-exported flat; each domain is a namespace.
+ */
+export * from './resolve';
+export * as education from './education';
+export * as eligibility from './eligibility';
+export * as org from './org';
+export * as paymaster from './paymaster';
+export * as project from './project';
+export * as task from './task';
+export * as token from './token';
+export * as treasury from './treasury';
+export * as user from './user';
+export * as vote from './vote';
+export * as zkemail from './zkemail';

package/dist/reads/index.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * Typed subgraph reads by domain. reads/resolve.ts (org resolution) is
+ * re-exported flat; each domain is a namespace.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.zkemail = exports.vote = exports.user = exports.treasury = exports.token = exports.task = exports.project = exports.paymaster = exports.org = exports.eligibility = exports.education = void 0;
+__exportStar(require("./resolve"), exports);
+exports.education = __importStar(require("./education"));
+exports.eligibility = __importStar(require("./eligibility"));
+exports.org = __importStar(require("./org"));
+exports.paymaster = __importStar(require("./paymaster"));
+exports.project = __importStar(require("./project"));
+exports.task = __importStar(require("./task"));
+exports.token = __importStar(require("./token"));
+exports.treasury = __importStar(require("./treasury"));
+exports.user = __importStar(require("./user"));
+exports.vote = __importStar(require("./vote"));
+exports.zkemail = __importStar(require("./zkemail"));

package/dist/reads/org.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Org reads — typed wrappers over the org subgraph documents.
+ *
+ * Ports the read layer of:
+ *   - `pop org view`    — src/commands/org/view.ts
+ *   - `pop org list`    — src/commands/org/list.ts
+ *   - `pop org members` — src/commands/org/members.ts
+ *   - `pop org roles`   — src/commands/org/roles.ts
+ *   - `pop org status`  — src/commands/org/status.ts (activity slice only; the
+ *     module-version panel is beacon/RPC machinery owned by the infra layer)
+ *
+ * Rows come back raw from the subgraph — a null row means "not indexed on
+ * this chain", which for a young org can mean "not indexed YET", not
+ * "nonexistent".
+ */
+import { ethers } from 'ethers';
+import type { GraphClient, ChainQueryResult } from '../graph/client';
+import type { InfrastructureAddresses } from '../graph/documents/infrastructure';
+import type { IpfsOptions } from '../ipfs';
+export interface OrgModuleRef {
+    id: string;
+}
+/** Raw Organization row as returned by FETCH_ORG_FULL_DATA. */
+export interface OrganizationFullRow {
+    id: string;
+    name: string | null;
+    metadataHash: string | null;
+    metadataAdminHatId: string | null;
+    metadata: Record<string, any> | null;
+    deployedAt: string | null;
+    topHatId: string | null;
+    roleHatIds: string[] | null;
+    participationToken: {
+        id: string;
+        name: string;
+        symbol: string;
+        totalSupply: string;
+    } | null;
+    quickJoin: OrgModuleRef | null;
+    hybridVoting: {
+        id: string;
+        thresholdPct: string | number;
+        quorum: string | number;
+    } | null;
+    directDemocracyVoting: {
+        id: string;
+        thresholdPct: string | number;
+        quorum: string | number;
+    } | null;
+    zkEmailInvites: OrgModuleRef | null;
+    taskManager: {
+        id: string;
+        creatorHatIds: string[] | null;
+        projects: Array<{
+            id: string;
+            tasks: Array<{
+                id: string;
+                status: string;
+            }>;
+        }>;
+    } | null;
+    educationHub: {
+        id: string;
+        modules: any[];
+    } | null;
+    executorContract: OrgModuleRef | null;
+    eligibilityModule: OrgModuleRef | null;
+    paymentManager: OrgModuleRef | null;
+    users: Array<{
+        id: string;
+        address: string;
+        account: {
+            username: string | null;
+            metadata: {
+                avatar: string | null;
+            } | null;
+        } | null;
+        participationTokenBalance: string;
+        membershipStatus: string;
+        currentHatIds: string[] | null;
+        totalTasksCompleted: string | null;
+        totalVotes: string | null;
+        firstSeenAt: string | null;
+    }>;
+    roles: Array<{
+        id: string;
+        hatId: string;
+        name: string | null;
+        image: string | null;
+        canVote: boolean;
+        isUserRole: boolean;
+        hat: {
+            name: string | null;
+        } | null;
+    }>;
+}
+/** Verbatim from src/commands/org/list.ts. */
+export declare const LIST_ORGS_QUERY = "\n  query ListOrgs($first: Int!) {\n    organizations(first: $first, orderBy: deployedAt, orderDirection: desc) {\n      id\n      name\n      deployedAt\n    }\n  }\n";
+/** Verbatim from src/commands/org/members.ts. */
+export declare const FETCH_MEMBERS = "\n  query FetchMembers($orgId: Bytes!) {\n    organization(id: $orgId) {\n      participationToken {\n        totalSupply\n      }\n      users(orderBy: participationTokenBalance, orderDirection: desc, first: 100) {\n        address\n        participationTokenBalance\n        membershipStatus\n        totalTasksCompleted\n        totalVotes\n        firstSeenAt\n        account {\n          username\n        }\n      }\n    }\n  }\n";
+/**
+ * Resolve an org name to its 0x id (passthrough for 0x input) — the name
+ * lookup `pop org view` performs. Returns null when the name matches nothing
+ * (unlike reads/resolve.resolveOrgId, which throws — view-style callers want
+ * "not found" as data).
+ */
+export declare function findOrgId(client: GraphClient, orgIdOrName: string, chainId?: number): Promise<string | null>;
+/**
+ * Port of the `pop org view` read — src/commands/org/view.ts.
+ * Full org snapshot (modules, roles, token, voting config, members) via
+ * FETCH_ORG_FULL_DATA. Accepts a name or 0x id; null when not indexed.
+ */
+export declare function getOrganization(client: GraphClient, orgIdOrName: string, chainId?: number): Promise<OrganizationFullRow | null>;
+/**
+ * The org's metadata document: the indexed projection when present, else the
+ * raw IPFS doc behind metadataHash (`pop org view` fallback). Never throws —
+ * null when neither source answers. NOTE: for the update-metadata merge base
+ * use the RAW IPFS doc, not this convenience read (see tx/org.ts).
+ */
+export declare function getOrgMetadataDoc(org: Pick<OrganizationFullRow, 'metadata' | 'metadataHash'>, ipfs?: IpfsOptions): Promise<Record<string, any> | null>;
+/**
+ * Current metadata-admin hat (0 = unset → topHat fallback) — port of
+ * readMetadataAdminHat in src/commands/org/view.ts.
+ *
+ * Subgraph-first: Organization.metadataAdminHatId is rewritten by
+ * handleOrgMetadataAdminHatSet on every OrgMetadataAdminHatSet event and is
+ * non-null on every live org. Only when the subgraph has no value AND a
+ * provider is supplied do we resolve the OrgRegistry and read the on-chain
+ * getter. Returns null when neither source is reachable; never throws.
+ * Display-only by convention — never gate a write on it.
+ */
+export declare function getMetadataAdminHat(client: GraphClient, orgId: string, chainId?: number, provider?: ethers.providers.Provider): Promise<string | null>;
+export interface OrgListRow {
+    id: string;
+    name: string | null;
+    deployedAt: string | null;
+}
+/**
+ * Port of the single-chain `pop org list` read — src/commands/org/list.ts.
+ */
+export declare function listOrgs(client: GraphClient, chainId?: number, first?: number): Promise<OrgListRow[]>;
+/**
+ * Port of the all-chain `pop org list` sweep — src/commands/org/list.ts.
+ * Per-chain failures are reported in ChainQueryResult.error, not thrown.
+ */
+export declare function listOrgsAllChains(client: GraphClient, first?: number): Promise<Array<ChainQueryResult<{
+    organizations: OrgListRow[];
+}>>>;
+export interface UserOrganizationRow {
+    id: string;
+    membershipStatus: string;
+    participationTokenBalance: string;
+    totalTasksCompleted: string | null;
+    totalVotes: string | null;
+    organization: {
+        id: string;
+        name: string | null;
+        metadataHash: string | null;
+        participationToken: {
+            symbol: string;
+        } | null;
+    } | null;
+}
+/**
+ * Port of the `pop org list --member` read — src/commands/org/list.ts
+ * (FETCH_USER_ORGANIZATIONS): active memberships for an address.
+ */
+export declare function listUserOrganizations(client: GraphClient, userAddress: string, chainId?: number): Promise<UserOrganizationRow[]>;
+export interface OrgMembersResult {
+    participationToken: {
+        totalSupply: string;
+    } | null;
+    users: Array<{
+        address: string;
+        participationTokenBalance: string;
+        membershipStatus: string;
+        totalTasksCompleted: string | null;
+        totalVotes: string | null;
+        firstSeenAt: string | null;
+        account: {
+            username: string | null;
+        } | null;
+    }>;
+}
+/**
+ * Port of the `pop org members` read — src/commands/org/members.ts.
+ * Raw member rows ordered by PT balance desc (top 100), plus totalSupply for
+ * share math. Null when the org is not indexed.
+ */
+export declare function listMembers(client: GraphClient, orgId: string, chainId?: number): Promise<OrgMembersResult | null>;
+export interface OrgRolesResult {
+    organization: {
+        roles: Array<{
+            id: string;
+            hatId: string;
+            name: string | null;
+            image: string | null;
+            canVote: boolean;
+            isUserRole: boolean;
+            /** Present only when tier 0 served (Hat.vouchConfig schema). */
+            hat?: {
+                id: string;
+                vouchConfig: {
+                    enabled: boolean;
+                    quorum: string;
+                    membershipHatId: string;
+                    combinesWithHierarchy: boolean;
+                } | null;
+            } | null;
+        }>;
+        users: Array<{
+            address: string;
+            participationTokenBalance: string;
+            membershipStatus: string;
+            currentHatIds: string[] | null;
+            account: {
+                username: string | null;
+            } | null;
+        }>;
+        eligibilityModule: {
+            id: string;
+        } | null;
+    } | null;
+}
+/**
+ * Port of the `pop org roles` read — src/commands/org/roles.ts.
+ *
+ * Tier 0 carries Role.hat.vouchConfig (present + populated on Gnosis and
+ * Arbitrum; a null vouchConfig means "never configured", verified equal to
+ * isVouchingEnabled()==false / quorum==0 on-chain). Tier 1 is the
+ * pre-vouchConfig schema; GraphQL validates the whole document, so the
+ * unknown-field fallback is what keeps older deployments working. When
+ * tierIndex === 1 serves, the CLI falls back to batched EligibilityModule
+ * reads through Multicall3 — that RPC path stays host-side.
+ */
+export declare function listRoles(client: GraphClient, orgId: string, chainId?: number): Promise<{
+    data: OrgRolesResult;
+    tierIndex: number;
+}>;
+/**
+ * Port of the `pop org status` activity read — src/commands/org/status.ts
+ * (FETCH_ORG_ACTIVITY). The extra module addresses scope the top-level
+ * proposal/vouch/token-request slices; the CLI passes '' for missing modules.
+ * Raw result; the status command's module-version panel (beacons/multicall)
+ * is separate infrastructure.
+ */
+export declare function getOrgActivity(client: GraphClient, modules: {
+    orgId: string;
+    hybridVotingAddress?: string | null;
+    eligibilityModuleAddress?: string | null;
+    participationTokenAddress?: string | null;
+}, chainId?: number): Promise<any>;
+/**
+ * Global infrastructure addresses (`FETCH_INFRASTRUCTURE_ADDRESSES`) — the
+ * OrgDeployer/OrgRegistry/PaymasterHub/UniversalAccountRegistry proxies and
+ * the beacon table.
+ */
+export declare function getInfrastructureAddresses(client: GraphClient, chainId?: number): Promise<InfrastructureAddresses>;

package/dist/reads/org.js

@@ -0,0 +1,220 @@
+"use strict";
+/**
+ * Org reads — typed wrappers over the org subgraph documents.
+ *
+ * Ports the read layer of:
+ *   - `pop org view`    — src/commands/org/view.ts
+ *   - `pop org list`    — src/commands/org/list.ts
+ *   - `pop org members` — src/commands/org/members.ts
+ *   - `pop org roles`   — src/commands/org/roles.ts
+ *   - `pop org status`  — src/commands/org/status.ts (activity slice only; the
+ *     module-version panel is beacon/RPC machinery owned by the infra layer)
+ *
+ * Rows come back raw from the subgraph — a null row means "not indexed on
+ * this chain", which for a young org can mean "not indexed YET", not
+ * "nonexistent".
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FETCH_MEMBERS = exports.LIST_ORGS_QUERY = void 0;
+exports.findOrgId = findOrgId;
+exports.getOrganization = getOrganization;
+exports.getOrgMetadataDoc = getOrgMetadataDoc;
+exports.getMetadataAdminHat = getMetadataAdminHat;
+exports.listOrgs = listOrgs;
+exports.listOrgsAllChains = listOrgsAllChains;
+exports.listUserOrganizations = listUserOrganizations;
+exports.listMembers = listMembers;
+exports.listRoles = listRoles;
+exports.getOrgActivity = getOrgActivity;
+exports.getInfrastructureAddresses = getInfrastructureAddresses;
+const org_1 = require("../graph/documents/org");
+const roles_1 = require("../graph/documents/roles");
+const activity_1 = require("../graph/documents/activity");
+const infrastructure_1 = require("../graph/documents/infrastructure");
+const contracts_1 = require("../contracts");
+const ipfs_1 = require("../ipfs");
+// ---------------------------------------------------------------------------
+// Inline documents ported from the org command files (not in src/queries)
+// ---------------------------------------------------------------------------
+/** Verbatim from src/commands/org/list.ts. */
+exports.LIST_ORGS_QUERY = `
+  query ListOrgs($first: Int!) {
+    organizations(first: $first, orderBy: deployedAt, orderDirection: desc) {
+      id
+      name
+      deployedAt
+    }
+  }
+`;
+/** Verbatim from src/commands/org/members.ts. */
+exports.FETCH_MEMBERS = `
+  query FetchMembers($orgId: Bytes!) {
+    organization(id: $orgId) {
+      participationToken {
+        totalSupply
+      }
+      users(orderBy: participationTokenBalance, orderDirection: desc, first: 100) {
+        address
+        participationTokenBalance
+        membershipStatus
+        totalTasksCompleted
+        totalVotes
+        firstSeenAt
+        account {
+          username
+        }
+      }
+    }
+  }
+`;
+// ---------------------------------------------------------------------------
+// Reads
+// ---------------------------------------------------------------------------
+/**
+ * Resolve an org name to its 0x id (passthrough for 0x input) — the name
+ * lookup `pop org view` performs. Returns null when the name matches nothing
+ * (unlike reads/resolve.resolveOrgId, which throws — view-style callers want
+ * "not found" as data).
+ */
+async function findOrgId(client, orgIdOrName, chainId) {
+    if (orgIdOrName.startsWith('0x'))
+        return orgIdOrName;
+    const result = await client.query(org_1.GET_ORG_BY_NAME, { name: orgIdOrName }, chainId);
+    return result.organizations?.[0]?.id ?? null;
+}
+/**
+ * Port of the `pop org view` read — src/commands/org/view.ts.
+ * Full org snapshot (modules, roles, token, voting config, members) via
+ * FETCH_ORG_FULL_DATA. Accepts a name or 0x id; null when not indexed.
+ */
+async function getOrganization(client, orgIdOrName, chainId) {
+    const orgId = await findOrgId(client, orgIdOrName, chainId);
+    if (!orgId)
+        return null;
+    const result = await client.query(org_1.FETCH_ORG_FULL_DATA, { orgId }, chainId);
+    return result.organization ?? null;
+}
+/**
+ * The org's metadata document: the indexed projection when present, else the
+ * raw IPFS doc behind metadataHash (`pop org view` fallback). Never throws —
+ * null when neither source answers. NOTE: for the update-metadata merge base
+ * use the RAW IPFS doc, not this convenience read (see tx/org.ts).
+ */
+async function getOrgMetadataDoc(org, ipfs) {
+    if (org.metadata)
+        return org.metadata;
+    if (!org.metadataHash)
+        return null;
+    try {
+        return await (0, ipfs_1.fetchJson)(org.metadataHash, ipfs);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Current metadata-admin hat (0 = unset → topHat fallback) — port of
+ * readMetadataAdminHat in src/commands/org/view.ts.
+ *
+ * Subgraph-first: Organization.metadataAdminHatId is rewritten by
+ * handleOrgMetadataAdminHatSet on every OrgMetadataAdminHatSet event and is
+ * non-null on every live org. Only when the subgraph has no value AND a
+ * provider is supplied do we resolve the OrgRegistry and read the on-chain
+ * getter. Returns null when neither source is reachable; never throws.
+ * Display-only by convention — never gate a write on it.
+ */
+async function getMetadataAdminHat(client, orgId, chainId, provider) {
+    try {
+        const result = await client.query(roles_1.FETCH_ORG_METADATA_ADMIN_HAT, { orgId }, chainId);
+        const fromSubgraph = result.organization?.metadataAdminHatId;
+        if (fromSubgraph !== undefined && fromSubgraph !== null) {
+            return String(fromSubgraph);
+        }
+    }
+    catch { /* fall through to RPC */ }
+    if (!provider)
+        return null;
+    try {
+        const infra = await client.query(infrastructure_1.FETCH_INFRASTRUCTURE_ADDRESSES, {}, chainId);
+        const orgRegistryAddr = infra.poaManagerContracts?.[0]?.orgRegistryProxy;
+        if (!orgRegistryAddr)
+            return null;
+        const registry = (0, contracts_1.createReadContract)(orgRegistryAddr, 'OrgRegistry', provider);
+        const hat = await registry.getOrgMetadataAdminHat(orgId);
+        return hat.toString();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Port of the single-chain `pop org list` read — src/commands/org/list.ts.
+ */
+async function listOrgs(client, chainId, first = 50) {
+    const result = await client.query(exports.LIST_ORGS_QUERY, { first }, chainId);
+    return result.organizations || [];
+}
+/**
+ * Port of the all-chain `pop org list` sweep — src/commands/org/list.ts.
+ * Per-chain failures are reported in ChainQueryResult.error, not thrown.
+ */
+async function listOrgsAllChains(client, first = 50) {
+    return client.queryAllChains(exports.LIST_ORGS_QUERY, { first });
+}
+/**
+ * Port of the `pop org list --member` read — src/commands/org/list.ts
+ * (FETCH_USER_ORGANIZATIONS): active memberships for an address.
+ */
+async function listUserOrganizations(client, userAddress, chainId) {
+    const result = await client.query(org_1.FETCH_USER_ORGANIZATIONS, { userAddress }, chainId);
+    return result.users || [];
+}
+/**
+ * Port of the `pop org members` read — src/commands/org/members.ts.
+ * Raw member rows ordered by PT balance desc (top 100), plus totalSupply for
+ * share math. Null when the org is not indexed.
+ */
+async function listMembers(client, orgId, chainId) {
+    const result = await client.query(exports.FETCH_MEMBERS, { orgId }, chainId);
+    return result.organization ?? null;
+}
+/**
+ * Port of the `pop org roles` read — src/commands/org/roles.ts.
+ *
+ * Tier 0 carries Role.hat.vouchConfig (present + populated on Gnosis and
+ * Arbitrum; a null vouchConfig means "never configured", verified equal to
+ * isVouchingEnabled()==false / quorum==0 on-chain). Tier 1 is the
+ * pre-vouchConfig schema; GraphQL validates the whole document, so the
+ * unknown-field fallback is what keeps older deployments working. When
+ * tierIndex === 1 serves, the CLI falls back to batched EligibilityModule
+ * reads through Multicall3 — that RPC path stays host-side.
+ */
+async function listRoles(client, orgId, chainId) {
+    return client.queryWithFieldFallback([
+        { query: roles_1.FETCH_ROLES_MEMBERS_AND_VOUCH, variables: { id: orgId } },
+        { query: roles_1.FETCH_ROLES_AND_MEMBERS, variables: { id: orgId } },
+    ], { chainId });
+}
+/**
+ * Port of the `pop org status` activity read — src/commands/org/status.ts
+ * (FETCH_ORG_ACTIVITY). The extra module addresses scope the top-level
+ * proposal/vouch/token-request slices; the CLI passes '' for missing modules.
+ * Raw result; the status command's module-version panel (beacons/multicall)
+ * is separate infrastructure.
+ */
+async function getOrgActivity(client, modules, chainId) {
+    return client.query(activity_1.FETCH_ORG_ACTIVITY, {
+        orgId: modules.orgId,
+        hybridVotingId: modules.hybridVotingAddress || '',
+        eligibilityModuleId: modules.eligibilityModuleAddress || '',
+        tokenAddress: modules.participationTokenAddress || '',
+    }, chainId);
+}
+/**
+ * Global infrastructure addresses (`FETCH_INFRASTRUCTURE_ADDRESSES`) — the
+ * OrgDeployer/OrgRegistry/PaymasterHub/UniversalAccountRegistry proxies and
+ * the beacon table.
+ */
+async function getInfrastructureAddresses(client, chainId) {
+    return client.query(infrastructure_1.FETCH_INFRASTRUCTURE_ADDRESSES, {}, chainId);
+}