@poa-box/core 0.1.0

package/dist/tx/task.d.ts

@@ -0,0 +1,480 @@
+/**
+ * Task-domain transaction builders (TaskManagerNew).
+ *
+ * Level 1 — pure builders (sync, zero I/O). One per contract write; they take
+ * resolved addresses + prepared values and return a TxIntent. ALL argument
+ * encoding lives here, byte-for-byte as the CLI encodes it: stringToBytes
+ * titles, ipfsCidToBytes32 hashes, parseUnits amounts (18d PT payouts, token
+ * registry decimals for bounties), and the v6/legacy createTask arity switch
+ * via TaskManagerFeatures + LEGACY_TM_FRAGMENTS.
+ *
+ * Level 2 — resolved builders (async, `<action>Intent(ctx, params)`). They
+ * resolve the org's TaskManager via reads/resolve, replicate the CLI's
+ * payout/pricing derivation and read-merge logic, pin metadata via ../ipfs,
+ * then delegate to the Level-1 builder. Duplicate checks, idempotency caches,
+ * confirmation prompts and lens pre-flights are CLI UX and are deliberately
+ * NOT ported.
+ */
+import { ethers } from 'ethers';
+import type { TxIntent } from './intent';
+import { type ExecutionCall } from './governance';
+import { type TaskManagerFeatures } from '../version';
+import type { PopContext } from '../context';
+/** TaskManager.ConfigKey.ROLE_PERM — verified enum index (src/commands/task/perms.ts:49). */
+export declare const CONFIG_KEY_ROLE_PERM = 2;
+/**
+ * parseDeadline for the update path: the contract deliberately accepts a
+ * PAST absolute deadline here (admin lever — immediately opens a CLAIMED
+ * task to takeover), so downgrade parseDeadline's past-check to a flag.
+ * Only absolute forms (unix seconds / ISO date) can resolve to the past —
+ * relative forms ("7d") are always future — so re-parsing with now=0 never
+ * changes relative math. Port of src/commands/task/update.ts parseUpdateDeadline.
+ */
+export declare function parseUpdateDeadline(input: string): {
+    value: number;
+    isPast: boolean;
+};
+/**
+ * Parse a folders-root input: CIDv0 (Qm…), 0x-prefixed bytes32, or "clear".
+ * Deliberately stricter than ipfsCidToBytes32 (which keccaks arbitrary
+ * strings — a silent footgun for a root pointer).
+ * Port of src/commands/task/folders.ts parseFoldersRoot.
+ */
+export declare function parseFoldersRoot(input: string): string;
+/**
+ * Parse a hat-id input (decimal or 0x hex) into a BigNumber.
+ * Port of src/commands/task/perms.ts parseHatId (same message).
+ */
+export declare function parseHatId(input: string | number | ethers.BigNumber): ethers.BigNumber;
+export interface CreateTaskArgs {
+    taskManagerAddress: string;
+    /** Human PT amount (18 decimals applied here, as `pop task create` does). */
+    payout: number | string;
+    /** Raw title; encoded with stringToBytes here. */
+    title: string;
+    /** CIDv0 or bytes32 metadata pointer; converted with ipfsCidToBytes32. */
+    metadataHash: string;
+    /** Resolved bytes32 project id. */
+    projectId: string;
+    /** ERC20 bounty token; defaults to AddressZero (no bounty). */
+    bountyToken?: string;
+    /** Human bounty amount; decimals come from the token registry. */
+    bountyAmount?: number | string;
+    requiresApplication?: boolean;
+    /** Unix seconds (0 = none). v6 orgs only — ignored on the legacy signature. */
+    absoluteDeadline?: number;
+    /** Seconds (0 = none). v6 orgs only — ignored on the legacy signature. */
+    completionWindow?: number;
+    /**
+     * Feature probe result: `deadlines` picks the 9-arg v6 createTask; without
+     * it the pre-v6 7-arg signature is encoded via LEGACY_TM_FRAGMENTS (the
+     * synced ABI no longer contains it).
+     */
+    features: Pick<TaskManagerFeatures, 'deadlines'>;
+    orgId?: string;
+}
+/**
+ * Port of `pop task create` — src/commands/task/create.ts (createTask send).
+ * v6 9-arg: [payoutWei, titleBytes, metadataHash, pid, bountyToken,
+ * bountyPayoutWei, requiresApplication, absoluteDeadline, completionWindow];
+ * legacy 7-arg drops the two deadline words and uses LEGACY_TM_FRAGMENTS.
+ */
+export declare function buildCreateTask(a: CreateTaskArgs): TxIntent;
+/** One row of a v6 createTasksBatch call (prepared values; NO pid inside). */
+export interface CreateTaskBatchRow {
+    /** Human PT amount (18 decimals applied here). */
+    payout: number | string;
+    title: string;
+    /** CIDv0 or bytes32. */
+    metadataHash: string;
+    bountyToken?: string;
+    bountyAmount?: number | string;
+    requiresApplication?: boolean;
+    /** Unix seconds (0 = none). */
+    absoluteDeadline?: number;
+    /** Seconds (0 = none). */
+    completionWindow?: number;
+}
+export interface CreateTasksBatchArgs {
+    taskManagerAddress: string;
+    /** Resolved bytes32 project id (shared by every row). */
+    projectId: string;
+    tasks: CreateTaskBatchRow[];
+    orgId?: string;
+}
+/**
+ * Port of `pop task create-batch` (v6 path) — src/commands/task/create-batch.ts.
+ * ONE all-or-nothing createTasksBatch(pid, CreateTaskInput[]) transaction.
+ * CreateTaskInput tuple field order must match the createTasksBatch components
+ * in the synced ABI (NOTE: no pid inside): payout, title, metadataHash,
+ * bountyToken, bountyPayout, requiresApplication, absoluteDeadline,
+ * completionWindow.
+ */
+export declare function buildCreateTasksBatch(a: CreateTasksBatchArgs): TxIntent;
+export interface TaskIdArgs {
+    taskManagerAddress: string;
+    /** Bare numeric id or subgraph composite `<taskManager>-<id>` (parsed here). */
+    taskId: string | number;
+    orgId?: string;
+}
+/** Port of `pop task claim` — src/commands/task/claim.ts (claimTask send). */
+export declare function buildClaimTask(a: TaskIdArgs): TxIntent;
+/**
+ * Port of `pop task unclaim` — src/commands/task/unclaim.ts (unclaimTask send).
+ * TaskManager v7 only; the feature gate lives in unclaimTaskIntent (the
+ * encoding itself is version-independent).
+ */
+export declare function buildUnclaimTask(a: TaskIdArgs): TxIntent;
+export interface SubmitTaskArgs extends TaskIdArgs {
+    /** CIDv0 or bytes32 pointer to the merged submission metadata document. */
+    submissionHash: string;
+}
+/** Port of `pop task submit` — src/commands/task/submit.ts (submitTask send). */
+export declare function buildSubmitTask(a: SubmitTaskArgs): TxIntent;
+/**
+ * Port of `pop task review --action approve` — src/commands/task/review.ts
+ * (completeTask send; releases payout + bounty to the claimer).
+ */
+export declare function buildCompleteTask(a: TaskIdArgs): TxIntent;
+export interface RejectTaskArgs extends TaskIdArgs {
+    /** CIDv0 or bytes32 pointer to the pinned `{rejection}` document. */
+    rejectionHash: string;
+}
+/**
+ * Port of `pop task review --action reject` — src/commands/task/review.ts
+ * (rejectTask send; no payout, task returns to CLAIMED).
+ */
+export declare function buildRejectTask(a: RejectTaskArgs): TxIntent;
+/** Port of `pop task cancel` — src/commands/task/cancel.ts (cancelTask send). */
+export declare function buildCancelTask(a: TaskIdArgs): TxIntent;
+export interface AssignTaskArgs extends TaskIdArgs {
+    /** Resolved assignee address. */
+    assignee: string;
+}
+/** Port of `pop task assign` — src/commands/task/assign.ts (assignTask send). */
+export declare function buildAssignTask(a: AssignTaskArgs): TxIntent;
+export interface ApplyForTaskArgs extends TaskIdArgs {
+    /** CIDv0 or bytes32 pointer to the pinned `{notes, experience}` document. */
+    applicationHash: string;
+}
+/** Port of `pop task apply` — src/commands/task/apply.ts (applyForTask send). */
+export declare function buildApplyForTask(a: ApplyForTaskArgs): TxIntent;
+export interface ApproveApplicationArgs extends TaskIdArgs {
+    applicant: string;
+}
+/**
+ * Port of `pop task approve-app` — src/commands/task/approve-application.ts
+ * (approveApplication send).
+ */
+export declare function buildApproveApplication(a: ApproveApplicationArgs): TxIntent;
+export interface UpdateTaskArgs extends TaskIdArgs {
+    /** MERGED final payout in wei (the CLI's read-merge produces wei values). */
+    payoutWei: ethers.BigNumberish;
+    /** Merged final title; encoded with stringToBytes here. */
+    title: string;
+    /** Merged final metadata pointer (CIDv0 or bytes32; '' ⇒ HashZero). */
+    metadataHash: string;
+    /** Merged final bounty token (AddressZero = none). */
+    bountyToken: string;
+    /** Merged final bounty payout in raw token units. */
+    bountyPayoutWei: ethers.BigNumberish;
+    /** Merged final absolute deadline (unix seconds; 0 = none). */
+    absoluteDeadline: number;
+    /** Merged final completion window (seconds; 0 = none). */
+    completionWindow: number;
+}
+/**
+ * Port of `pop task update` — src/commands/task/update.ts (updateTask send).
+ * updateTask is a FULL OVERWRITE on-chain (8-arg v6 signature): every field is
+ * the merged FINAL value, in wei — use updateTaskIntent for the read-merge.
+ * The CLI refuses the pre-v6 6-field signature entirely (features.deadlines
+ * gate), so this builder only ever emits the v6 shape.
+ */
+export declare function buildUpdateTask(a: UpdateTaskArgs): TxIntent;
+export interface UpdateTaskMetadataArgs extends TaskIdArgs {
+    /** Merged final title; encoded with stringToBytes here. */
+    title: string;
+    /** Merged final metadata pointer (CIDv0 or bytes32). */
+    metadataHash: string;
+}
+/**
+ * Port of `pop task edit-meta` — src/commands/task/edit-meta.ts
+ * (updateTaskMetadata send). v5+; preserves payout/bounty on-chain but fully
+ * overwrites the title + metadata pointer pair.
+ */
+export declare function buildUpdateTaskMetadata(a: UpdateTaskMetadataArgs): TxIntent;
+export interface SetProjectRolePermArgs {
+    taskManagerAddress: string;
+    /** Resolved bytes32 project id. */
+    projectId: string;
+    hatId: ethers.BigNumberish;
+    /** TaskPerm bitmask (uint8). */
+    mask: number;
+    orgId?: string;
+}
+/**
+ * Port of `pop task perms set` — src/commands/task/perms.ts:309
+ * (setProjectRolePerm send; creator-hat/executor gate stays on-chain).
+ */
+export declare function buildSetProjectRolePerm(a: SetProjectRolePermArgs): TxIntent;
+/**
+ * The executor-gated setConfig(ROLE_PERM, abi.encode(uint256 hatId, uint8
+ * mask)) call `pop task perms propose-global` wraps in a proposal —
+ * src/commands/task/perms.ts:418. The CLI encodes via an inline
+ * `setConfig(uint8,bytes)` interface; the synced TaskManagerNew ABI carries
+ * the same signature, so the calldata is byte-identical.
+ */
+export declare function buildSetGlobalRolePermCall(taskManagerAddress: string, hatId: ethers.BigNumberish, mask: number): ExecutionCall;
+export interface ProposeGlobalRolePermArgs {
+    hybridVotingAddress: string;
+    taskManagerAddress: string;
+    hatId: ethers.BigNumberish;
+    mask: number;
+    durationMinutes: ethers.BigNumberish;
+    /** bytes32 of the pinned proposal metadata (ipfsCidToBytes32 applied by caller or here via CID). */
+    descriptionHash: string;
+    orgId?: string;
+}
+/**
+ * Port of `pop task perms propose-global` — src/commands/task/perms.ts:400.
+ * HybridVoting.createProposal(titleBytes, descriptionHash, duration, 2,
+ * [[setConfig call], []], []) — option 0 applies the mask, option 1 keeps
+ * current. Title matches the CLI's deterministic string.
+ */
+export declare function buildProposeGlobalRolePerm(a: ProposeGlobalRolePermArgs): TxIntent;
+export interface SetFoldersArgs {
+    taskManagerAddress: string;
+    /** CAS guard: the root believed current (read over RPC, never the subgraph). */
+    expectedCurrentRoot: string;
+    /** New bytes32 root (use parseFoldersRoot for Qm…/'clear' inputs). */
+    newRoot: string;
+    orgId?: string;
+}
+/**
+ * Port of `pop task folders set` — src/commands/task/folders.ts:286
+ * (setFolders send). CAS-guarded: reverts FoldersRootStale when
+ * expectedCurrentRoot no longer matches; the CLI's read-retry-once loop is
+ * execution-time behavior and stays host-side.
+ */
+export declare function buildSetFolders(a: SetFoldersArgs): TxIntent;
+export interface CreateTaskParams {
+    org: string;
+    /** Project name, bytes32 pid, or numeric index (resolved like the CLI). */
+    project: string;
+    name: string;
+    description: string;
+    /** Omit to price the task from the org's payout convention (refuses to guess when the subgraph is down). */
+    payout?: number;
+    difficulty?: string;
+    estHours?: number;
+    location?: string;
+    bountyToken?: string;
+    bountyAmount?: number;
+    requiresApplication?: boolean;
+    /** '7d' / ISO / unix (string forms parsed like the CLI); v6 orgs only. */
+    deadline?: string | number;
+    /** '48h' / seconds; v6 orgs only. */
+    completionWindow?: string | number;
+    /** Skip detection (offline hosts). */
+    features?: TaskManagerFeatures;
+}
+/**
+ * Port of `pop task create` — src/commands/task/create.ts. Resolves the org +
+ * project, feature-gates the deadline flags, derives the payout exactly as
+ * the web app would when omitted, pins the canonical metadata document, and
+ * delegates to buildCreateTask. Duplicate-check and idempotency are CLI UX
+ * and are not ported.
+ */
+export declare function createTaskIntent(ctx: PopContext, p: CreateTaskParams): Promise<TxIntent>;
+/** One JSONL row of `pop task create-batch` (the file parsing stays host-side). */
+export interface CreateTaskBatchRowParams {
+    name: string;
+    description: string;
+    payout?: number;
+    difficulty?: string;
+    estHours?: number;
+    location?: string;
+    bountyToken?: string;
+    bountyAmount?: number;
+    requiresApplication?: boolean;
+    /** Per-row absolute claim deadline (overrides the batch default; v6 only). */
+    deadline?: string | number;
+    /** Per-row completion window (overrides the batch default; v6 only). */
+    completionWindow?: string | number;
+}
+export interface CreateTasksBatchParams {
+    org: string;
+    /** Passed straight through parseProjectId, as the CLI does (no title lookup). */
+    project: string;
+    tasks: CreateTaskBatchRowParams[];
+    /** Batch-wide defaults; rows may override. */
+    deadline?: string | number;
+    completionWindow?: string | number;
+    features?: TaskManagerFeatures;
+}
+/**
+ * Port of `pop task create-batch` — src/commands/task/create-batch.ts.
+ * Returns ONE createTasksBatch intent (all-or-nothing) on v6 orgs, or one
+ * legacy 7-arg createTask intent PER ROW on pre-v6 orgs (the CLI sends those
+ * sequentially; --continue-on-error is host-side execution policy). Per-row
+ * metadata is pinned in input order so receipt TaskCreated logs line up.
+ */
+export declare function createTasksBatchIntents(ctx: PopContext, p: CreateTasksBatchParams): Promise<TxIntent[]>;
+export interface TaskActionParams {
+    org: string;
+    /** Bare numeric id or subgraph composite `<taskManager>-<id>`. */
+    task: string | number;
+}
+/** Port of `pop task claim` — src/commands/task/claim.ts. */
+export declare function claimTaskIntent(ctx: PopContext, p: TaskActionParams): Promise<TxIntent>;
+export interface UnclaimTaskParams extends TaskActionParams {
+    features?: TaskManagerFeatures;
+}
+/**
+ * Port of `pop task unclaim` — src/commands/task/unclaim.ts (TaskManager v7).
+ * Feature-gated like the CLI when a provider (or features override) is
+ * available; without either the gate is skipped — the encoding is identical
+ * and the contract is the authority. The self-vs-force consent tiering and
+ * the lens gate are host UX.
+ */
+export declare function unclaimTaskIntent(ctx: PopContext, p: UnclaimTaskParams): Promise<TxIntent>;
+export interface SubmitTaskParams extends TaskActionParams {
+    submission: string;
+}
+/**
+ * Port of `pop task submit` — src/commands/task/submit.ts. The submission is
+ * a FULL OVERWRITE of the task's metadata pointer, so the current document is
+ * read first (subgraph → IPFS fallback) and merged; when the base is
+ * unrecoverable this REFUSES (exit INFRA) rather than blanking the task's
+ * name/description/dueDate. Pre-flight (CLAIMED + claimer) is host UX.
+ */
+export declare function submitTaskIntent(ctx: PopContext, p: SubmitTaskParams): Promise<TxIntent>;
+/** Port of `pop task review --action approve` — src/commands/task/review.ts. */
+export declare function completeTaskIntent(ctx: PopContext, p: TaskActionParams): Promise<TxIntent>;
+export interface RejectTaskParams extends TaskActionParams {
+    /** Rejection reason (the CLI requires --reason for reject). */
+    reason: string;
+}
+/**
+ * Port of `pop task review --action reject` — src/commands/task/review.ts.
+ * Pins the `{rejection}` document, then builds rejectTask. (The CLI pins
+ * after pre-flight + confirm; core has neither, so the pin is the first step.)
+ */
+export declare function rejectTaskIntent(ctx: PopContext, p: RejectTaskParams): Promise<TxIntent>;
+/** Port of `pop task cancel` — src/commands/task/cancel.ts (DESTRUCTIVE; consent is host UX). */
+export declare function cancelTaskIntent(ctx: PopContext, p: TaskActionParams): Promise<TxIntent>;
+export interface AssignTaskParams extends TaskActionParams {
+    /** Assignee address (checksummed via requireAddress). */
+    assignee?: string;
+    /** Or a username, resolved across all chains like the CLI. */
+    username?: string;
+}
+/**
+ * Port of `pop task assign` — src/commands/task/assign.ts. --username resolves
+ * via the same inline all-chains accounts query; --assignee is validated as an
+ * address. One of the two is required.
+ */
+export declare function assignTaskIntent(ctx: PopContext, p: AssignTaskParams): Promise<TxIntent>;
+export interface ApplyForTaskParams extends TaskActionParams {
+    notes?: string;
+    experience?: string;
+}
+/**
+ * Port of `pop task apply` — src/commands/task/apply.ts. Pins the
+ * `{notes, experience}` document, then builds applyForTask. The
+ * requiresApplication / duplicate-application pre-flights are host UX (the
+ * contract's NoApplicationRequired / AlreadyApplied decodes are authoritative).
+ */
+export declare function applyForTaskIntent(ctx: PopContext, p: ApplyForTaskParams): Promise<TxIntent>;
+export interface ApproveApplicationParams extends TaskActionParams {
+    applicant: string;
+}
+/** Port of `pop task approve-app` — src/commands/task/approve-application.ts. */
+export declare function approveApplicationIntent(ctx: PopContext, p: ApproveApplicationParams): Promise<TxIntent>;
+export interface UpdateTaskParams extends TaskActionParams {
+    payout?: number;
+    name?: string;
+    description?: string;
+    /** ERC20 address, or 'none' to clear the bounty. */
+    bountyToken?: string;
+    bountyAmount?: number;
+    /** A PAST value is deliberately accepted (admin takeover lever). */
+    deadline?: string;
+    completionWindow?: string;
+    features?: TaskManagerFeatures;
+}
+/**
+ * Port of `pop task update` — src/commands/task/update.ts. updateTask is a
+ * FULL OVERWRITE on-chain, so this reads the current state first (chain via
+ * the task lens for payout/bounty/deadlines — ctx.provider required; subgraph
+ * + IPFS for title/description/metadata), merges only the fields given, and
+ * re-pins metadata ONLY when name/description actually change. Refuses (INFRA)
+ * when the overwrite base is unrecoverable. A past deadline is accepted and
+ * flagged in meta.summary.deadlineIsPast.
+ */
+export declare function updateTaskIntent(ctx: PopContext, p: UpdateTaskParams): Promise<TxIntent>;
+export interface EditTaskMetadataParams extends TaskActionParams {
+    name?: string;
+    description?: string;
+    features?: TaskManagerFeatures;
+}
+/**
+ * Port of `pop task edit-meta` — src/commands/task/edit-meta.ts
+ * (updateTaskMetadata; TaskManager v5+). Reads the current name/description
+ * (subgraph → IPFS fallback), merges, and re-pins. Returns NULL when the merge
+ * is a no-op — the CLI short-circuits with success and never sends. The
+ * terminal-status read uses the lens when ctx.provider is present (parity);
+ * without one, the contract's BadStatus revert is the authority.
+ */
+export declare function editTaskMetadataIntent(ctx: PopContext, p: EditTaskMetadataParams): Promise<TxIntent | null>;
+export interface SetProjectRolePermParams {
+    org: string;
+    /** Project bytes32 id or title (resolved via the perms tiers, like the CLI). */
+    project: string;
+    /** Hat id (decimal or 0x hex). */
+    hat: string | number | ethers.BigNumber;
+    /** Comma-separated permission list ('create,claim' / 'none') or a raw mask. */
+    perms: string | number;
+}
+/**
+ * Port of `pop task perms set` — src/commands/task/perms.ts:309. Resolves the
+ * project by hex or title (PERMS_QUERY_FULL/LEGACY tiers), parses the perm
+ * list into a mask, and builds setProjectRolePerm. The creator-hat/executor
+ * gate stays on-chain (masks are not readable per-wearer).
+ */
+export declare function setProjectRolePermIntent(ctx: PopContext, p: SetProjectRolePermParams): Promise<TxIntent>;
+export interface ProposeGlobalRolePermParams {
+    org: string;
+    hat: string | number | ethers.BigNumber;
+    perms: string | number;
+    /** Vote duration in minutes (CLI default 60). */
+    duration?: number;
+}
+/**
+ * Port of `pop task perms propose-global` — src/commands/task/perms.ts:400.
+ * setConfig(ROLE_PERM) is executor-only, so the change ships as a HybridVoting
+ * proposal whose option-0 batch targets the TaskManager. Pins the proposal
+ * metadata {description, optionNames, createdAt} (exact key order), then
+ * delegates to buildProposeGlobalRolePerm.
+ */
+export declare function proposeGlobalRolePermIntent(ctx: PopContext, p: ProposeGlobalRolePermParams): Promise<TxIntent>;
+export interface SetFoldersParams {
+    org: string;
+    /** New folder-tree root: Qm… CIDv0, 0x-prefixed bytes32, or "clear". */
+    newRoot: string;
+    /**
+     * CAS guard override. When omitted it is read from chain via the lens
+     * (ctx.provider required) — deliberately NEVER the subgraph: a stale value
+     * guarantees the FoldersRootStale revert this read exists to predict.
+     */
+    expectedCurrentRoot?: string;
+    features?: TaskManagerFeatures;
+}
+/**
+ * Port of `pop task folders set` — src/commands/task/folders.ts:286
+ * (TaskManager v4+). Parses the new root, auto-fills the CAS expected root
+ * from chain, and returns NULL when the root already matches (the CLI reports
+ * success without sending). The stale-root retry-once loop is execution-time
+ * behavior and stays host-side.
+ */
+export declare function setFoldersIntent(ctx: PopContext, p: SetFoldersParams): Promise<TxIntent | null>;