@tetsuo-ai/marketplace-react 0.1.1 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (58) hide show
  1. package/CHANGELOG.md +21 -3
  2. package/README.md +50 -20
  3. package/dist/{chunk-ABS77JB2.js → chunk-D2TDU3TJ.js} +3 -3
  4. package/dist/{chunk-ABS77JB2.js.map → chunk-D2TDU3TJ.js.map} +1 -1
  5. package/dist/{chunk-GN5DYVN5.js → chunk-ECU7HGO3.js} +6 -5
  6. package/dist/chunk-ECU7HGO3.js.map +1 -0
  7. package/dist/{chunk-YORZNYZZ.js → chunk-FAIRTAIB.js} +53 -17
  8. package/dist/chunk-FAIRTAIB.js.map +1 -0
  9. package/dist/{chunk-5OTKSRHM.js → chunk-MNJ2EQDJ.js} +3 -3
  10. package/dist/{chunk-5OTKSRHM.js.map → chunk-MNJ2EQDJ.js.map} +1 -1
  11. package/dist/{chunk-A7ETZFNH.js → chunk-WJUVTFJ7.js} +6 -6
  12. package/dist/chunk-WJUVTFJ7.js.map +1 -0
  13. package/dist/components/index.cjs +47 -16
  14. package/dist/components/index.cjs.map +1 -1
  15. package/dist/components/index.d.cts +2 -2
  16. package/dist/components/index.d.ts +2 -2
  17. package/dist/components/index.js +3 -3
  18. package/dist/hooks/index.cjs +350 -28
  19. package/dist/hooks/index.cjs.map +1 -1
  20. package/dist/hooks/index.d.cts +160 -36
  21. package/dist/hooks/index.d.ts +160 -36
  22. package/dist/hooks/index.js +299 -19
  23. package/dist/hooks/index.js.map +1 -1
  24. package/dist/{index-zLJX8XdK.d.ts → index-C9R3B80j.d.ts} +29 -37
  25. package/dist/{index-DUsGVhDz.d.cts → index-CTTh1ZPg.d.cts} +29 -37
  26. package/dist/index.cjs +68 -32
  27. package/dist/index.cjs.map +1 -1
  28. package/dist/index.d.cts +10 -19
  29. package/dist/index.d.ts +10 -19
  30. package/dist/index.js +17 -12
  31. package/dist/index.js.map +1 -1
  32. package/dist/signers/index.cjs +4 -3
  33. package/dist/signers/index.cjs.map +1 -1
  34. package/dist/signers/index.js +2 -2
  35. package/dist/{useAgentTrackRecord-BLf1nrbu.d.cts → useAgentTrackRecord-BCvRHYM2.d.cts} +7 -7
  36. package/dist/{useAgentTrackRecord-BLf1nrbu.d.ts → useAgentTrackRecord-BCvRHYM2.d.ts} +7 -7
  37. package/package.json +3 -2
  38. package/src/components/HireButton.tsx +1 -2
  39. package/src/components/HireCheckoutModal.tsx +8 -9
  40. package/src/components/ReferrerDisclosure.tsx +8 -12
  41. package/src/components/strings.ts +2 -2
  42. package/src/hooks/index.ts +47 -4
  43. package/src/hooks/internal.ts +74 -2
  44. package/src/hooks/useHire.ts +30 -38
  45. package/src/hooks/useHumanlessHireFlow.ts +259 -0
  46. package/src/hooks/useRateHire.ts +52 -0
  47. package/src/hooks/useReferrerEarnings.ts +32 -33
  48. package/src/hooks/useTaskActivation.ts +58 -0
  49. package/src/hooks/useTaskLifecycle.ts +110 -0
  50. package/src/hooks/useTaskWork.ts +76 -0
  51. package/src/index.ts +2 -2
  52. package/src/provider/AgencProvider.tsx +3 -3
  53. package/src/provider/referrer.ts +24 -32
  54. package/src/strings/index.ts +5 -3
  55. package/src/types.ts +7 -10
  56. package/dist/chunk-A7ETZFNH.js.map +0 -1
  57. package/dist/chunk-GN5DYVN5.js.map +0 -1
  58. package/dist/chunk-YORZNYZZ.js.map +0 -1
@@ -1,14 +1,11 @@
1
1
  /**
2
2
  * `<ReferrerDisclosure>` — the "this site earns a referral fee" notice.
3
3
  *
4
- * ## THE P6.2 GATE (PLAN_2 §0 / the §0 referrer gate — read before editing)
4
+ * ## Referral disclosure
5
5
  *
6
- * Disclosure is the ONE referrer surface allowed to render while the on-chain
7
- * referrer leg is not live. It NEVER asserts that a fee was charged: when
8
- * `live` is false it shows the "(pending protocol support)" copy. It is purely
9
- * informational and reads no earnings. The actual injection / earnings remain
10
- * blocked on P6.2 (handled by the hooks, not here). This component only
11
- * DISCLOSES the configured intent.
6
+ * Disclosure is informational and reads no earnings. When `live` is true it can
7
+ * use the present-tense fee copy. When `live` is false it shows neutral copy and
8
+ * does not imply a fee was charged.
12
9
  *
13
10
  * Render it only when a referrer is configured on the provider.
14
11
  *
@@ -24,9 +21,8 @@ export interface ReferrerDisclosureProps extends ThemableProps {
24
21
  /** The validated referrer config (from the provider context). */
25
22
  referrer: ValidatedReferrerConfig;
26
23
  /**
27
- * Whether the referral fee is actually live on-chain (the P6.2 capability).
28
- * ALWAYS false today — when false the copy shows the pending-support note and
29
- * no fee is implied as charged. Defaults to false.
24
+ * Whether the referral fee is active for this hire. When false, no fee is
25
+ * implied as charged. Defaults to false.
30
26
  */
31
27
  live?: boolean;
32
28
  /** Show the configured fee in bps alongside the disclosure. Default true. */
@@ -34,8 +30,8 @@ export interface ReferrerDisclosureProps extends ThemableProps {
34
30
  }
35
31
 
36
32
  /**
37
- * Disclose that the embedding site earns a referral fee. Honors the P6.2 gate:
38
- * shows the pending-support copy until referral settlement is live.
33
+ * Disclose that the embedding site earns a referral fee when referral settlement
34
+ * is active for the hire.
39
35
  */
40
36
  export function ReferrerDisclosure({
41
37
  referrer,
@@ -62,10 +62,10 @@ export const EN_COMPONENT_STRINGS = {
62
62
  "components.hire.moderationIssues": "Moderation issues found",
63
63
  "components.hire.notConnected": "Connect a wallet to hire.",
64
64
 
65
- // Referrer disclosure (P6.2 gate — never claims a live fee).
65
+ // Referrer disclosure.
66
66
  "components.referrer.disclosure": "This site earns a referral fee.",
67
67
  "components.referrer.disclosurePending":
68
- "This site earns a referral fee (pending protocol support).",
68
+ "Referral fee is not active for this hire.",
69
69
  "components.referrer.feeBps": "{bps} bps",
70
70
 
71
71
  // TaskTimeline.
@@ -5,9 +5,9 @@
5
5
  * Query (bundled), surfaces typed `AgencError`s from the runtime client
6
6
  * UNTOUCHED, and is SSR-safe (no `window`/`document` at module scope).
7
7
  *
8
- * Referrer-related surfaces (`useHire`'s injection, `useReferrerEarnings`) are
9
- * gated by the P6.2 capability check: not-live today, so no referrer is ever
10
- * injected and no earnings are ever fabricated.
8
+ * Referrer-related surfaces are split deliberately: `useHire` injects a
9
+ * configured referrer into live settlement, while `useReferrerEarnings` remains
10
+ * indexer-gated so no earnings are ever fabricated.
11
11
  *
12
12
  * @module hooks
13
13
  */
@@ -62,6 +62,49 @@ export {
62
62
  type ReviewStatus,
63
63
  type UseSubmissionReviewResult,
64
64
  } from "./useSubmissionReview.js";
65
+ export {
66
+ useTaskActivation,
67
+ type TaskActivationInput,
68
+ type TaskActivationStatus,
69
+ type UseTaskActivationResult,
70
+ } from "./useTaskActivation.js";
71
+ export {
72
+ useHumanlessHireFlow,
73
+ type HumanlessHireFlowActivationInput,
74
+ type HumanlessHireFlowCreator,
75
+ type HumanlessHireFlowHireInput,
76
+ type HumanlessHireFlowHost,
77
+ type HumanlessHireFlowHostInput,
78
+ type HumanlessHireFlowInput,
79
+ type HumanlessHireFlowJobSpecHash,
80
+ type HumanlessHireFlowModerationResult,
81
+ type HumanlessHireFlowPhase,
82
+ type HumanlessHireFlowProgress,
83
+ type HumanlessHireFlowResult,
84
+ type HumanlessHireFlowStatus,
85
+ type UseHumanlessHireFlowResult,
86
+ } from "./useHumanlessHireFlow.js";
87
+ export {
88
+ useTaskWork,
89
+ type ClaimTaskInput,
90
+ type SubmitTaskResultInput,
91
+ type TaskWorkStatus,
92
+ type UseTaskWorkResult,
93
+ } from "./useTaskWork.js";
94
+ export {
95
+ useTaskLifecycle,
96
+ type AutoAcceptTaskResultInput,
97
+ type CancelTaskInput,
98
+ type CloseTaskInput,
99
+ type TaskLifecycleStatus,
100
+ type UseTaskLifecycleResult,
101
+ } from "./useTaskLifecycle.js";
102
+ export {
103
+ useRateHire,
104
+ type RateHireInput,
105
+ type RateHireStatus,
106
+ type UseRateHireResult,
107
+ } from "./useRateHire.js";
65
108
  export {
66
109
  useDispute,
67
110
  type DisputeReader,
@@ -79,7 +122,7 @@ export {
79
122
  type WalletSignerAdapter,
80
123
  } from "./useWalletSigner.js";
81
124
 
82
- // Referrer earnings (P6.2-gated)
125
+ // Referrer earnings (indexer-gated)
83
126
  export {
84
127
  useReferrerEarnings,
85
128
  type ReferrerHire,
@@ -12,7 +12,12 @@
12
12
  * @module hooks/internal
13
13
  */
14
14
  import { t } from "../strings/index.js";
15
- import type { Address, MarketplaceClient } from "../types.js";
15
+ import type {
16
+ Address,
17
+ AgencContextValue,
18
+ MarketplaceClient,
19
+ TransactionSigner,
20
+ } from "../types.js";
16
21
 
17
22
  /** Root namespace for every cache key this package writes. */
18
23
  export const QUERY_KEY_ROOT = "agenc" as const;
@@ -40,7 +45,7 @@ export const queryKeys = {
40
45
  [QUERY_KEY_ROOT, "taskStatus", taskPda] as const,
41
46
  /** One task's dispute record. */
42
47
  dispute: (taskPda: string) => [QUERY_KEY_ROOT, "dispute", taskPda] as const,
43
- /** One referrer wallet's earnings (P6.2-gated; see useReferrerEarnings). */
48
+ /** One referrer wallet's earnings (indexer-gated; see useReferrerEarnings). */
44
49
  referrerEarnings: (wallet: string) =>
45
50
  [QUERY_KEY_ROOT, "referrerEarnings", wallet] as const,
46
51
  } as const;
@@ -64,7 +69,74 @@ export function requireClient(
64
69
  return client;
65
70
  }
66
71
 
72
+ export type MutationStatus = "idle" | "pending" | "success" | "error";
73
+
74
+ export function mutationStatusOf(mutation: {
75
+ isPending: boolean;
76
+ isError: boolean;
77
+ isSuccess: boolean;
78
+ }): MutationStatus {
79
+ if (mutation.isPending) return "pending";
80
+ if (mutation.isError) return "error";
81
+ if (mutation.isSuccess) return "success";
82
+ return "idle";
83
+ }
84
+
67
85
  /** Coerce an `Address | string` to its string form for use as a cache key. */
68
86
  export function pdaKey(pda: Address | string): string {
69
87
  return String(pda);
70
88
  }
89
+
90
+ export interface ReferrerArgs {
91
+ referrer?: Address;
92
+ referrerFeeBps?: number;
93
+ }
94
+
95
+ export interface ResolvedReferrerArgs {
96
+ referrerArgs: ReferrerArgs;
97
+ referrerInjected: boolean;
98
+ }
99
+
100
+ export function resolveReferrerArgs(
101
+ ctx: Pick<AgencContextValue, "resolveReferrerCapability">,
102
+ ): ResolvedReferrerArgs {
103
+ const capability = ctx.resolveReferrerCapability();
104
+ if (!capability.live || !capability.referrer) {
105
+ return { referrerArgs: {}, referrerInjected: false };
106
+ }
107
+ return {
108
+ referrerArgs: {
109
+ referrer: capability.referrer.wallet,
110
+ referrerFeeBps: capability.referrer.feeBps,
111
+ },
112
+ referrerInjected: true,
113
+ };
114
+ }
115
+
116
+ export type SignerOrAddress = TransactionSigner | Address;
117
+
118
+ export function signerAddress(signerOrAddress: SignerOrAddress): Address {
119
+ if (typeof signerOrAddress === "string") {
120
+ return signerOrAddress;
121
+ }
122
+ if (
123
+ typeof signerOrAddress === "object" &&
124
+ signerOrAddress !== null &&
125
+ "address" in signerOrAddress &&
126
+ typeof signerOrAddress.address === "string"
127
+ ) {
128
+ return signerOrAddress.address;
129
+ }
130
+ throw new Error("Expected a TransactionSigner or Address with an address field.");
131
+ }
132
+
133
+ export function withoutReferrerArgs<T extends object>(
134
+ input: T,
135
+ ): Omit<T, "referrer" | "referrerFeeBps"> {
136
+ const {
137
+ referrer: _referrer,
138
+ referrerFeeBps: _referrerFeeBps,
139
+ ...rest
140
+ } = input as T & { referrer?: unknown; referrerFeeBps?: unknown };
141
+ return rest;
142
+ }
@@ -5,32 +5,29 @@
5
5
  * surfaces the resulting transaction signature + minted Task PDA. Typed
6
6
  * `AgencError`s from the runtime client are surfaced UNTOUCHED in `error`.
7
7
  *
8
- * ## THE P6.2 REFERRER GATE (PLAN_2 §0, MANDATORY — read before editing)
8
+ * ## REFERRER SETTLEMENT
9
9
  *
10
- * The on-chain referrer args + 4th settlement leg (PLAN.md P6.2) are UNBUILT.
11
- * The SDK `facade.hireFromListing` has NO referrer parameter. So this hook:
10
+ * The full 84-instruction protocol supports a demand-side referrer leg. This hook:
12
11
  * - reads `resolveReferrerCapability()` from context BEFORE building the hire;
13
- * - when `live === false` (ALWAYS, today): it injects NO referrer argument into
14
- * the hire input. The referrer config is still accepted/validated/stored on
15
- * the provider and disclosure UI may show the pending-support copy — but the
16
- * transaction the user signs is a plain hire with no referral leg.
17
- * - the `referrerInjected` flag in the result is the audit signal: it is `false`
18
- * today and would only become `true` once P6.2 is live AND a referrer is
19
- * configured. We NEVER fabricate it.
20
- *
21
- * When P6.2 ships, the ONLY change here is: under `capability.live === true`,
22
- * spread the referrer fields (`referrer`, `referrerFeeBps`) into the hire input
23
- * below. Nothing else moves.
12
+ * - when `live === true`, spreads the validated provider referrer into the hire
13
+ * input for both standard and humanless hires;
14
+ * - the `referrerInjected` flag in the result is the audit signal. We never set
15
+ * it true unless the transaction input included the referrer fields.
24
16
  *
25
17
  * @module hooks/useHire
26
18
  */
27
19
  import { useMutation } from "@tanstack/react-query";
28
20
  import { useCallback, useMemo } from "react";
29
- import { facade, findTaskPda } from "@tetsuo-ai/marketplace-sdk";
21
+ import { findTaskPda } from "@tetsuo-ai/marketplace-sdk";
30
22
  import type { facade as facadeNs } from "@tetsuo-ai/marketplace-sdk";
31
23
  import { useAgencContext } from "../provider/context.js";
32
24
  import type { Address } from "../types.js";
33
- import { requireClient } from "./internal.js";
25
+ import {
26
+ requireClient,
27
+ resolveReferrerArgs,
28
+ signerAddress,
29
+ withoutReferrerArgs,
30
+ } from "./internal.js";
34
31
 
35
32
  /**
36
33
  * Input to a standard `hire(...)` — a buyer that has a registered marketplace
@@ -39,12 +36,12 @@ import { requireClient } from "./internal.js";
39
36
  * MINUS the fee-payer signers, which default to the provider's write-client
40
37
  * signer (authority == creator == buyer). Pass them only to override.
41
38
  *
42
- * NOTE: deliberately NO referrer field — the referrer is provider-level config,
43
- * gated by P6.2, and is never threaded through a per-call hire input.
39
+ * NOTE: deliberately NO referrer field — the referrer is provider-level config
40
+ * and is injected only when `resolveReferrerCapability()` is live.
44
41
  */
45
42
  export type HireInput = Omit<
46
43
  Parameters<typeof facadeNs.hireFromListing>[0],
47
- "authority" | "creator"
44
+ "authority" | "creator" | "referrer" | "referrerFeeBps"
48
45
  > & {
49
46
  /** Standard hire (default). */
50
47
  humanless?: false;
@@ -64,7 +61,7 @@ export type HireInput = Omit<
64
61
  */
65
62
  export type HumanlessHireInput = Omit<
66
63
  Parameters<typeof facadeNs.hireFromListingHumanless>[0],
67
- "creator"
64
+ "creator" | "referrer" | "referrerFeeBps"
68
65
  > & {
69
66
  /** Discriminates the humanless storefront-visitor hire. */
70
67
  humanless: true;
@@ -85,8 +82,8 @@ export interface HireResult {
85
82
  /** The minted Task PDA (derived from creator + taskId). */
86
83
  taskPda: Address;
87
84
  /**
88
- * Whether a referrer fee leg was injected into THIS hire. Always `false`
89
- * today (the P6.2 gate). Audit signal — never fabricated.
85
+ * Whether a referrer fee leg was injected into THIS hire. Audit signal —
86
+ * never fabricated.
90
87
  */
91
88
  referrerInjected: boolean;
92
89
  }
@@ -130,12 +127,10 @@ export function useHire(): UseHireResult {
130
127
  mutationFn: async (input: AnyHireInput): Promise<HireResult> => {
131
128
  const client = requireClient(ctx.client);
132
129
 
133
- // --- THE P6.2 GATE ---
134
- // Capability is resolved fresh per hire. Today it is ALWAYS not-live, so
135
- // we build a referrer-free hire. When P6.2 lands, the `capability.live`
136
- // branch is where the referrer fields get spread in (for BOTH paths).
137
- const capability = ctx.resolveReferrerCapability();
138
- const referrerInjected = capability.live && ctx.referrer !== null;
130
+ // Resolve fresh per hire so a provider referrer config change cannot leak
131
+ // stale referral terms into a new transaction.
132
+ const { referrerArgs, referrerInjected } = resolveReferrerArgs(ctx);
133
+ const hireInput = withoutReferrerArgs(input);
139
134
 
140
135
  const creator = input.creator ?? client.signer;
141
136
  let signature: string;
@@ -143,30 +138,27 @@ export function useHire(): UseHireResult {
143
138
  if (input.humanless === true) {
144
139
  // Storefront-visitor hire: no creator agent; CreatorReview-pinned, so
145
140
  // it settles via the buyer review path (useSubmissionReview).
146
- const ix = await facade.hireFromListingHumanless({
147
- ...input,
141
+ const result = await client.hireFromListingHumanless({
142
+ ...hireInput,
148
143
  creator,
149
- // NOTE: P6.2 referrer fields would spread here under capability.live.
144
+ ...referrerArgs,
150
145
  } as Parameters<typeof facadeNs.hireFromListingHumanless>[0]);
151
- ({ signature } = await client.send([ix]));
146
+ signature = result.signature;
152
147
  } else {
153
148
  // Standard hire: authority == creator == buyer (the buyer has an agent).
154
149
  const authority = input.authority ?? client.signer;
155
150
  const result = await client.hireFromListing({
156
- ...input,
151
+ ...hireInput,
157
152
  authority,
158
153
  creator,
159
- // NOTE: P6.2 referrer fields would spread here under capability.live.
154
+ ...referrerArgs,
160
155
  } as Parameters<typeof facadeNs.hireFromListing>[0]);
161
156
  signature = result.signature;
162
157
  }
163
158
 
164
159
  // Derive the minted Task PDA from (creator, taskId).
165
160
  const [taskPda] = await findTaskPda({
166
- creator:
167
- typeof creator === "object" && creator !== null && "address" in creator
168
- ? creator.address
169
- : (creator as Address),
161
+ creator: signerAddress(creator),
170
162
  taskId: input.taskId,
171
163
  });
172
164
 
@@ -0,0 +1,259 @@
1
+ import { useMutation } from "@tanstack/react-query";
2
+ import { useCallback, useRef, useState } from "react";
3
+ import { findTaskPda } from "@tetsuo-ai/marketplace-sdk";
4
+ import type { facade as facadeNs } from "@tetsuo-ai/marketplace-sdk";
5
+ import { useAgencContext } from "../provider/context.js";
6
+ import type { Address } from "../types.js";
7
+ import {
8
+ mutationStatusOf,
9
+ requireClient,
10
+ resolveReferrerArgs,
11
+ signerAddress,
12
+ withoutReferrerArgs,
13
+ type MutationStatus,
14
+ } from "./internal.js";
15
+ import type { HumanlessHireInput } from "./useHire.js";
16
+ import type { TaskActivationInput } from "./useTaskActivation.js";
17
+
18
+ export type HumanlessHireFlowPhase =
19
+ | "idle"
20
+ | "hiring"
21
+ | "moderating"
22
+ | "activating"
23
+ | "activated"
24
+ | "error";
25
+
26
+ export type HumanlessHireFlowStatus = MutationStatus;
27
+
28
+ export type HumanlessHireFlowHireInput = Omit<
29
+ HumanlessHireInput,
30
+ "humanless" | "creator" | "referrer" | "referrerFeeBps"
31
+ >;
32
+
33
+ export type HumanlessHireFlowActivationInput = Omit<
34
+ TaskActivationInput,
35
+ "creator" | "jobSpecHash" | "jobSpecUri"
36
+ >;
37
+
38
+ export type HumanlessHireFlowCreator = HumanlessHireInput["creator"];
39
+
40
+ export type HumanlessHireFlowJobSpecHash =
41
+ Parameters<typeof facadeNs.setTaskJobSpec>[0]["jobSpecHash"];
42
+
43
+ export interface HumanlessHireFlowModerationResult {
44
+ jobSpecHash: HumanlessHireFlowJobSpecHash;
45
+ jobSpecUri: string;
46
+ moderationAttested: boolean;
47
+ moderation?: unknown;
48
+ }
49
+
50
+ export interface HumanlessHireFlowHostInput<TJobSpec> {
51
+ taskPda: Address;
52
+ taskId: HumanlessHireFlowHireInput["taskId"];
53
+ listing: HumanlessHireFlowHireInput["listing"];
54
+ jobSpec: TJobSpec;
55
+ hireSignature: string;
56
+ referrerInjected: boolean;
57
+ }
58
+
59
+ export type HumanlessHireFlowHost<TJobSpec> = (
60
+ input: HumanlessHireFlowHostInput<TJobSpec>,
61
+ ) => Promise<HumanlessHireFlowModerationResult>;
62
+
63
+ export interface HumanlessHireFlowInput<TJobSpec = unknown> {
64
+ hire: HumanlessHireFlowHireInput;
65
+ jobSpec: TJobSpec;
66
+ hostAndModerateJobSpec: HumanlessHireFlowHost<TJobSpec>;
67
+ activation?: HumanlessHireFlowActivationInput;
68
+ creator?: HumanlessHireFlowCreator;
69
+ }
70
+
71
+ export interface HumanlessHireFlowProgress {
72
+ taskPda: Address | null;
73
+ hireSignature: string | null;
74
+ activationSignature: string | null;
75
+ jobSpecHash: HumanlessHireFlowJobSpecHash | null;
76
+ jobSpecUri: string | null;
77
+ referrerInjected: boolean;
78
+ }
79
+
80
+ export interface HumanlessHireFlowResult {
81
+ taskPda: Address;
82
+ hireSignature: string;
83
+ activationSignature: string;
84
+ jobSpecHash: HumanlessHireFlowJobSpecHash;
85
+ jobSpecUri: string;
86
+ referrerInjected: boolean;
87
+ moderation?: unknown;
88
+ }
89
+
90
+ export interface UseHumanlessHireFlowResult<TJobSpec = unknown> {
91
+ hireAndActivate: (
92
+ input: HumanlessHireFlowInput<TJobSpec>,
93
+ ) => Promise<HumanlessHireFlowResult>;
94
+ phase: HumanlessHireFlowPhase;
95
+ status: HumanlessHireFlowStatus;
96
+ progress: HumanlessHireFlowProgress;
97
+ result: HumanlessHireFlowResult | null;
98
+ error: Error | null;
99
+ isPending: boolean;
100
+ reset: () => void;
101
+ }
102
+
103
+ function emptyProgress(): HumanlessHireFlowProgress {
104
+ return {
105
+ taskPda: null,
106
+ hireSignature: null,
107
+ activationSignature: null,
108
+ jobSpecHash: null,
109
+ jobSpecUri: null,
110
+ referrerInjected: false,
111
+ };
112
+ }
113
+
114
+ function validateModerationResult(
115
+ result: HumanlessHireFlowModerationResult,
116
+ ): { jobSpecHash: HumanlessHireFlowJobSpecHash; jobSpecUri: string } {
117
+ if (result.moderationAttested !== true) {
118
+ throw new Error(
119
+ "Task moderation was not attested; activation was not signed.",
120
+ );
121
+ }
122
+ if (
123
+ !(result.jobSpecHash instanceof Uint8Array) ||
124
+ result.jobSpecHash.byteLength !== 32
125
+ ) {
126
+ throw new Error(
127
+ "Task moderation returned an invalid jobSpecHash; activation was not signed.",
128
+ );
129
+ }
130
+ const jobSpecUri = result.jobSpecUri.trim();
131
+ if (!jobSpecUri) {
132
+ throw new Error(
133
+ "Task moderation returned an empty jobSpecUri; activation was not signed.",
134
+ );
135
+ }
136
+ return { jobSpecHash: result.jobSpecHash, jobSpecUri };
137
+ }
138
+
139
+ export function useHumanlessHireFlow<TJobSpec = unknown>(): UseHumanlessHireFlowResult<TJobSpec> {
140
+ const ctx = useAgencContext();
141
+ const [phase, setPhase] = useState<HumanlessHireFlowPhase>("idle");
142
+ const [progress, setProgress] =
143
+ useState<HumanlessHireFlowProgress>(emptyProgress);
144
+ const flowInFlight = useRef(false);
145
+
146
+ const mutation = useMutation<
147
+ HumanlessHireFlowResult,
148
+ Error,
149
+ HumanlessHireFlowInput<TJobSpec>
150
+ >({
151
+ mutationFn: async (input) => {
152
+ const client = requireClient(ctx.client);
153
+ const creator = input.creator ?? client.signer;
154
+ const { referrerArgs, referrerInjected } = resolveReferrerArgs(ctx);
155
+ const hireInput = withoutReferrerArgs(input.hire);
156
+
157
+ setPhase("hiring");
158
+ setProgress(emptyProgress());
159
+
160
+ try {
161
+ const hireResult = await client.hireFromListingHumanless({
162
+ ...hireInput,
163
+ creator,
164
+ ...referrerArgs,
165
+ } as Parameters<typeof facadeNs.hireFromListingHumanless>[0]);
166
+
167
+ const [taskPda] = await findTaskPda({
168
+ creator: signerAddress(creator),
169
+ taskId: input.hire.taskId,
170
+ });
171
+
172
+ setProgress({
173
+ ...emptyProgress(),
174
+ taskPda,
175
+ hireSignature: hireResult.signature,
176
+ referrerInjected,
177
+ });
178
+
179
+ setPhase("moderating");
180
+ const moderation = await input.hostAndModerateJobSpec({
181
+ taskPda,
182
+ taskId: input.hire.taskId,
183
+ listing: input.hire.listing,
184
+ jobSpec: input.jobSpec,
185
+ hireSignature: hireResult.signature,
186
+ referrerInjected,
187
+ });
188
+ const { jobSpecHash, jobSpecUri } = validateModerationResult(moderation);
189
+
190
+ setProgress((current) => ({
191
+ ...current,
192
+ jobSpecHash,
193
+ jobSpecUri,
194
+ }));
195
+
196
+ setPhase("activating");
197
+ const activationResult = await client.setTaskJobSpec({
198
+ ...(input.activation ?? {}),
199
+ task: taskPda,
200
+ creator,
201
+ jobSpecHash,
202
+ jobSpecUri,
203
+ } as Parameters<typeof facadeNs.setTaskJobSpec>[0]);
204
+
205
+ const result: HumanlessHireFlowResult = {
206
+ taskPda,
207
+ hireSignature: hireResult.signature,
208
+ activationSignature: activationResult.signature,
209
+ jobSpecHash,
210
+ jobSpecUri,
211
+ referrerInjected,
212
+ moderation: moderation.moderation,
213
+ };
214
+
215
+ setProgress((current) => ({
216
+ ...current,
217
+ activationSignature: activationResult.signature,
218
+ }));
219
+ setPhase("activated");
220
+ return result;
221
+ } catch (error) {
222
+ setPhase("error");
223
+ throw error;
224
+ }
225
+ },
226
+ });
227
+
228
+ const hireAndActivate = useCallback(
229
+ async (input: HumanlessHireFlowInput<TJobSpec>) => {
230
+ if (flowInFlight.current) {
231
+ throw new Error("A humanless hire flow is already in progress.");
232
+ }
233
+ flowInFlight.current = true;
234
+ try {
235
+ return await mutation.mutateAsync(input);
236
+ } finally {
237
+ flowInFlight.current = false;
238
+ }
239
+ },
240
+ [mutation],
241
+ );
242
+
243
+ const reset = useCallback(() => {
244
+ mutation.reset();
245
+ setPhase("idle");
246
+ setProgress(emptyProgress());
247
+ }, [mutation]);
248
+
249
+ return {
250
+ hireAndActivate,
251
+ phase,
252
+ status: mutationStatusOf(mutation),
253
+ progress,
254
+ result: mutation.data ?? null,
255
+ error: mutation.error ?? null,
256
+ isPending: mutation.isPending,
257
+ reset,
258
+ };
259
+ }
@@ -0,0 +1,52 @@
1
+ import { useMutation } from "@tanstack/react-query";
2
+ import { useCallback } from "react";
3
+ import type { facade as facadeNs } from "@tetsuo-ai/marketplace-sdk";
4
+ import { useAgencContext } from "../provider/context.js";
5
+ import {
6
+ mutationStatusOf,
7
+ requireClient,
8
+ type MutationStatus,
9
+ } from "./internal.js";
10
+
11
+ export type RateHireInput = Omit<
12
+ Parameters<typeof facadeNs.rateHire>[0],
13
+ "task" | "buyer"
14
+ > & {
15
+ buyer?: Parameters<typeof facadeNs.rateHire>[0]["buyer"];
16
+ };
17
+ export type RateHireStatus = MutationStatus;
18
+
19
+ export interface UseRateHireResult {
20
+ rate: (input: RateHireInput) => Promise<string>;
21
+ status: RateHireStatus;
22
+ signature: string | null;
23
+ error: Error | null;
24
+ isPending: boolean;
25
+ reset: () => void;
26
+ }
27
+
28
+ export function useRateHire(
29
+ taskPda: Parameters<typeof facadeNs.rateHire>[0]["task"],
30
+ ): UseRateHireResult {
31
+ const ctx = useAgencContext();
32
+ const mutation = useMutation<string, Error, RateHireInput>({
33
+ mutationFn: async (input) => {
34
+ const client = requireClient(ctx.client);
35
+ const { signature } = await client.rateHire({
36
+ ...input,
37
+ task: taskPda,
38
+ buyer: input.buyer ?? client.signer,
39
+ } as Parameters<typeof facadeNs.rateHire>[0]);
40
+ return signature;
41
+ },
42
+ });
43
+ const rate = useCallback((input: RateHireInput) => mutation.mutateAsync(input), [mutation]);
44
+ return {
45
+ rate,
46
+ status: mutationStatusOf(mutation),
47
+ signature: mutation.data ?? null,
48
+ error: mutation.error ?? null,
49
+ isPending: mutation.isPending,
50
+ reset: mutation.reset,
51
+ };
52
+ }