@poa-box/core 0.1.0

package/dist/encoding.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Encoding Utilities
+ * Direct port of frontend encoding.js for byte-identical behavior.
+ * Uses ethers v5 + bs58 v6 to match frontend exactly.
+ */
+export declare function stringToBytes(str: string): Uint8Array;
+export declare function bytesToString(bytes: Uint8Array): string;
+export declare function stringToBytes32(str: string): string;
+/**
+ * Encode IPFS CIDv0 (Qm...) to bytes32.
+ * CIDv0 = base58(0x1220 + 32-byte-sha256-hash)
+ * We store just the 32-byte hash portion.
+ */
+export declare function ipfsCidToBytes32(cid: string): string;
+/**
+ * Decode bytes32 back to IPFS CIDv0.
+ */
+export declare function bytes32ToIpfsCid(bytes32Hash: string): string | null;
+/**
+ * Parse a task ID from subgraph format.
+ * Subgraph returns IDs like "contractAddress-taskId", contract expects numeric taskId.
+ */
+export declare function parseTaskId(taskId: string | number): string;
+export declare function parseModuleId(moduleId: string | number): string;
+/**
+ * Parse a project ID from subgraph format.
+ * Subgraph: "{contractAddress}-{projectId}" where projectId is bytes32 hex.
+ */
+export declare function parseProjectId(projectId: string): string;
+export declare function formatAddress(address: string, chars?: number): string;
+export declare function isValidAddress(address: string): boolean;
+export declare function toChecksumAddress(address: string): string;
+/**
+ * Parse a deadline expression into unix seconds.
+ *
+ * Accepted forms:
+ *   - ''or '0'            → 0 (no deadline)
+ *   - relative            → '7d', '48h', '90m', '3600s' (added to `now`)
+ *   - unix seconds        → bare digits >= 10^9, e.g. '1790000000'
+ *   - ISO date            → '2026-08-01' (treated as UTC midnight)
+ *   - ISO datetime        → '2026-08-01T12:30:00' or '...Z' / '...+02:00'
+ *                           (no timezone suffix → treated as UTC)
+ *
+ * Throws CliError when the input is unparseable, exceeds the uint48
+ * range, or resolves to a timestamp at/before `now`.
+ */
+export declare function parseDeadline(input: string, now?: number): number;
+/**
+ * Parse a duration expression into seconds.
+ * Accepts bare seconds ('3600') or s/m/h/d suffixes ('48h', '7d').
+ * '0' → 0. Throws CliError when unparseable or above the uint32 max.
+ */
+export declare function parseDurationSeconds(input: string): number;
+/**
+ * Format a unix-second deadline as 'YYYY-MM-DD HH:mm UTC'.
+ * 0 (no deadline) → 'none'.
+ */
+export declare function formatDeadline(unixSecs: number): string;

package/dist/encoding.js

@@ -0,0 +1,243 @@
+"use strict";
+/**
+ * Encoding Utilities
+ * Direct port of frontend encoding.js for byte-identical behavior.
+ * Uses ethers v5 + bs58 v6 to match frontend exactly.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stringToBytes = stringToBytes;
+exports.bytesToString = bytesToString;
+exports.stringToBytes32 = stringToBytes32;
+exports.ipfsCidToBytes32 = ipfsCidToBytes32;
+exports.bytes32ToIpfsCid = bytes32ToIpfsCid;
+exports.parseTaskId = parseTaskId;
+exports.parseModuleId = parseModuleId;
+exports.parseProjectId = parseProjectId;
+exports.formatAddress = formatAddress;
+exports.isValidAddress = isValidAddress;
+exports.toChecksumAddress = toChecksumAddress;
+exports.parseDeadline = parseDeadline;
+exports.parseDurationSeconds = parseDurationSeconds;
+exports.formatDeadline = formatDeadline;
+const ethers_1 = require("ethers");
+const bs58_1 = __importDefault(require("bs58"));
+const errors_1 = require("./errors");
+function stringToBytes(str) {
+    return ethers_1.ethers.utils.toUtf8Bytes(str);
+}
+function bytesToString(bytes) {
+    return ethers_1.ethers.utils.toUtf8String(bytes);
+}
+function stringToBytes32(str) {
+    if (!str)
+        return ethers_1.ethers.constants.HashZero;
+    return ethers_1.ethers.utils.keccak256(ethers_1.ethers.utils.toUtf8Bytes(str));
+}
+/**
+ * Encode IPFS CIDv0 (Qm...) to bytes32.
+ * CIDv0 = base58(0x1220 + 32-byte-sha256-hash)
+ * We store just the 32-byte hash portion.
+ */
+function ipfsCidToBytes32(cid) {
+    if (!cid || cid === '') {
+        return ethers_1.ethers.constants.HashZero;
+    }
+    if (!cid.startsWith('Qm')) {
+        if (cid.startsWith('0x') && cid.length === 66) {
+            return cid;
+        }
+        return stringToBytes32(cid);
+    }
+    try {
+        const decoded = bs58_1.default.decode(cid);
+        if (decoded.length !== 34) {
+            console.error(`Invalid CIDv0 length: expected 34 bytes, got ${decoded.length}`);
+            return ethers_1.ethers.constants.HashZero;
+        }
+        const hashBytes = decoded.slice(2);
+        return ethers_1.ethers.utils.hexlify(hashBytes);
+    }
+    catch (error) {
+        console.error('Failed to encode IPFS CID to bytes32:', error);
+        return ethers_1.ethers.constants.HashZero;
+    }
+}
+/**
+ * Decode bytes32 back to IPFS CIDv0.
+ */
+function bytes32ToIpfsCid(bytes32Hash) {
+    if (!bytes32Hash || bytes32Hash === ethers_1.ethers.constants.HashZero)
+        return null;
+    try {
+        const hashBytes = ethers_1.ethers.utils.arrayify(bytes32Hash);
+        const withPrefix = new Uint8Array([0x12, 0x20, ...hashBytes]);
+        return bs58_1.default.encode(withPrefix);
+    }
+    catch (error) {
+        console.warn('Failed to decode bytes32 to IPFS CID:', error);
+        return null;
+    }
+}
+/**
+ * Parse a task ID from subgraph format.
+ * Subgraph returns IDs like "contractAddress-taskId", contract expects numeric taskId.
+ */
+function parseTaskId(taskId) {
+    const taskIdStr = taskId.toString();
+    const result = taskIdStr.includes('-') ? taskIdStr.split('-')[1] : taskIdStr;
+    if (!result) {
+        throw new Error(`Invalid task ID format: "${taskId}"`);
+    }
+    return result;
+}
+function parseModuleId(moduleId) {
+    const moduleIdStr = moduleId.toString();
+    const result = moduleIdStr.includes('-') ? moduleIdStr.split('-')[1] : moduleIdStr;
+    if (!result) {
+        throw new Error(`Invalid module ID format: "${moduleId}"`);
+    }
+    return result;
+}
+/**
+ * Parse a project ID from subgraph format.
+ * Subgraph: "{contractAddress}-{projectId}" where projectId is bytes32 hex.
+ */
+function parseProjectId(projectId) {
+    if (!projectId) {
+        return ethers_1.ethers.constants.HashZero;
+    }
+    if (projectId.startsWith('0x') && projectId.length === 66) {
+        return projectId;
+    }
+    const subgraphPattern = /^0x[a-fA-F0-9]{40}-(.+)$/;
+    const match = projectId.match(subgraphPattern);
+    if (match) {
+        const extractedId = match[1];
+        if (extractedId.startsWith('0x') && extractedId.length === 66) {
+            return extractedId;
+        }
+        if (/^[a-fA-F0-9]+$/.test(extractedId)) {
+            return ethers_1.ethers.utils.hexZeroPad('0x' + extractedId, 32);
+        }
+    }
+    return stringToBytes32(projectId);
+}
+function formatAddress(address, chars = 4) {
+    if (!address)
+        return '';
+    return `${address.slice(0, chars + 2)}...${address.slice(-chars)}`;
+}
+function isValidAddress(address) {
+    return ethers_1.ethers.utils.isAddress(address);
+}
+function toChecksumAddress(address) {
+    return ethers_1.ethers.utils.getAddress(address);
+}
+/** Contracts store deadlines as uint48. */
+const UINT48_MAX = 2 ** 48 - 1;
+/** Contracts store durations as uint32. */
+const UINT32_MAX = 2 ** 32 - 1;
+const DURATION_MULTIPLIERS = {
+    s: 1,
+    m: 60,
+    h: 3600,
+    d: 86400,
+};
+/**
+ * Parse a deadline expression into unix seconds.
+ *
+ * Accepted forms:
+ *   - ''or '0'            → 0 (no deadline)
+ *   - relative            → '7d', '48h', '90m', '3600s' (added to `now`)
+ *   - unix seconds        → bare digits >= 10^9, e.g. '1790000000'
+ *   - ISO date            → '2026-08-01' (treated as UTC midnight)
+ *   - ISO datetime        → '2026-08-01T12:30:00' or '...Z' / '...+02:00'
+ *                           (no timezone suffix → treated as UTC)
+ *
+ * Throws CliError when the input is unparseable, exceeds the uint48
+ * range, or resolves to a timestamp at/before `now`.
+ */
+function parseDeadline(input, now) {
+    const nowSecs = now ?? Math.floor(Date.now() / 1000);
+    const trimmed = (input || '').trim();
+    if (trimmed === '' || trimmed === '0')
+        return 0;
+    let result;
+    const relative = trimmed.match(/^(\d+)([smhd])$/i);
+    if (relative) {
+        result = nowSecs + parseInt(relative[1], 10) * DURATION_MULTIPLIERS[relative[2].toLowerCase()];
+    }
+    else if (/^\d+$/.test(trimmed)) {
+        const num = parseInt(trimmed, 10);
+        if (num < 1e9) {
+            throw new errors_1.CliError(`Ambiguous deadline "${input}": bare numbers must be unix-second timestamps (>= 1000000000).`, 1, 'Use a relative deadline like "7d" or "48h", an ISO date like "2026-08-01", or a full unix timestamp.');
+        }
+        result = num;
+    }
+    else if (/^\d{4}-\d{2}-\d{2}$/.test(trimmed)) {
+        const ms = Date.parse(`${trimmed}T00:00:00Z`);
+        if (Number.isNaN(ms)) {
+            throw new errors_1.CliError(`Invalid date "${input}".`, 1, 'Use an ISO date like "2026-08-01".');
+        }
+        result = Math.floor(ms / 1000);
+    }
+    else if (/^\d{4}-\d{2}-\d{2}[T ]/.test(trimmed)) {
+        const normalized = trimmed.replace(' ', 'T');
+        // No timezone suffix → treat as UTC for deterministic behavior
+        const hasTz = /(?:Z|[+-]\d{2}:?\d{2})$/i.test(normalized);
+        const ms = Date.parse(hasTz ? normalized : `${normalized}Z`);
+        if (Number.isNaN(ms)) {
+            throw new errors_1.CliError(`Invalid datetime "${input}".`, 1, 'Use ISO format like "2026-08-01T12:30:00Z".');
+        }
+        result = Math.floor(ms / 1000);
+    }
+    else {
+        throw new errors_1.CliError(`Unparseable deadline "${input}".`, 1, 'Use a relative deadline ("7d", "48h", "90m", "3600s"), an ISO date ("2026-08-01"), a unix timestamp, or "0" for no deadline.');
+    }
+    if (result > UINT48_MAX) {
+        throw new errors_1.CliError(`Deadline "${input}" exceeds the uint48 range (max ${UINT48_MAX}).`);
+    }
+    if (result <= nowSecs) {
+        throw new errors_1.CliError(`Deadline "${input}" is in the past (resolved to ${formatDeadline(result)}).`, 1, 'Pick a future date, or pass "0" for no deadline.');
+    }
+    return result;
+}
+/**
+ * Parse a duration expression into seconds.
+ * Accepts bare seconds ('3600') or s/m/h/d suffixes ('48h', '7d').
+ * '0' → 0. Throws CliError when unparseable or above the uint32 max.
+ */
+function parseDurationSeconds(input) {
+    const trimmed = (input || '').trim();
+    if (trimmed === '0')
+        return 0;
+    let seconds;
+    const relative = trimmed.match(/^(\d+)([smhd])$/i);
+    if (relative) {
+        seconds = parseInt(relative[1], 10) * DURATION_MULTIPLIERS[relative[2].toLowerCase()];
+    }
+    else if (/^\d+$/.test(trimmed)) {
+        seconds = parseInt(trimmed, 10);
+    }
+    else {
+        throw new errors_1.CliError(`Unparseable duration "${input}".`, 1, 'Use bare seconds ("3600") or a suffix: "3600s", "90m", "48h", "7d".');
+    }
+    if (seconds > UINT32_MAX) {
+        throw new errors_1.CliError(`Duration "${input}" exceeds the uint32 range (max ${UINT32_MAX} seconds).`);
+    }
+    return seconds;
+}
+/**
+ * Format a unix-second deadline as 'YYYY-MM-DD HH:mm UTC'.
+ * 0 (no deadline) → 'none'.
+ */
+function formatDeadline(unixSecs) {
+    if (!unixSecs)
+        return 'none';
+    const d = new Date(unixSecs * 1000);
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${d.getUTCFullYear()}-${pad(d.getUTCMonth() + 1)}-${pad(d.getUTCDate())} ${pad(d.getUTCHours())}:${pad(d.getUTCMinutes())} UTC`;
+}

package/dist/env.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Environment injection seam.
+ *
+ * @poa-box/core never reads process.env. Hosts pass an EnvSource where env-derived
+ * behavior is wanted: the CLI passes process.env, a Next.js frontend passes an
+ * object built from NEXT_PUBLIC_* values, tests pass literals, and integrators
+ * who want pure defaults pass nothing.
+ */
+export type EnvSource = Record<string, string | undefined>;
+export declare const EMPTY_ENV: EnvSource;

package/dist/env.js

@@ -0,0 +1,4 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMPTY_ENV = void 0;
+exports.EMPTY_ENV = {};

package/dist/error-catalog.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Contract Error Catalog
+ * Decodes custom contract errors (4-byte selector + ABI-encoded args) from
+ * revert data into human-readable messages with actionable suggestions.
+ * Covers every custom error declared across the generated abis/ registry
+ * via a lazily-built selector registry. test/lib/error-catalog.test.ts
+ * enforces that ERROR_MESSAGES stays in sync with the ABIs.
+ */
+import { ethers } from 'ethers';
+export interface DecodedContractError {
+    name: string;
+    args: any[];
+    human: string;
+    suggestion?: string;
+}
+/**
+ * Decode custom-error revert data from an ethers v5 error object.
+ * Tries the caller-supplied interface first (most specific), then the global
+ * registry built from all generated ABI error fragments.
+ *
+ * Returns null when no revert data is present, or for plain Error(string) /
+ * Panic(uint256) reverts — those already surface via error.reason. Unknown
+ * selectors return a generic UnknownCustomError(<selector>) result.
+ */
+export declare function decodeContractError(error: any, iface?: ethers.utils.Interface): DecodedContractError | null;
+/**
+ * Human messages + suggestions for every distinct custom error name across
+ * all generated ABIs. The drift guard in test/lib/error-catalog.test.ts
+ * fails if an ABI regeneration introduces a name without an entry here.
+ */
+export declare const ERROR_MESSAGES: Record<string, {
+    human: string;
+    suggestion?: string;
+}>;
+/**
+ * Look up the human message + suggestion for a custom error name.
+ */
+export declare function getErrorHint(name: string): {
+    human: string;
+    suggestion?: string;
+} | undefined;