@tetsuo-ai/marketplace-react 0.1.0 → 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 (65) hide show
  1. package/CHANGELOG.md +29 -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-KJMR6OGC.js → chunk-WJUVTFJ7.js} +105 -9
  12. package/dist/chunk-WJUVTFJ7.js.map +1 -0
  13. package/dist/components/agenc-components.css +20 -0
  14. package/dist/components/index.cjs +147 -17
  15. package/dist/components/index.cjs.map +1 -1
  16. package/dist/components/index.d.cts +2 -2
  17. package/dist/components/index.d.ts +2 -2
  18. package/dist/components/index.js +3 -3
  19. package/dist/hooks/index.cjs +350 -28
  20. package/dist/hooks/index.cjs.map +1 -1
  21. package/dist/hooks/index.d.cts +160 -36
  22. package/dist/hooks/index.d.ts +160 -36
  23. package/dist/hooks/index.js +299 -19
  24. package/dist/hooks/index.js.map +1 -1
  25. package/dist/{index-BLrlBVj-.d.cts → index-C9R3B80j.d.ts} +176 -47
  26. package/dist/{index-CKTYsNPH.d.ts → index-CTTh1ZPg.d.cts} +176 -47
  27. package/dist/index.cjs +168 -33
  28. package/dist/index.cjs.map +1 -1
  29. package/dist/index.d.cts +10 -19
  30. package/dist/index.d.ts +10 -19
  31. package/dist/index.js +17 -12
  32. package/dist/index.js.map +1 -1
  33. package/dist/signers/index.cjs +4 -3
  34. package/dist/signers/index.cjs.map +1 -1
  35. package/dist/signers/index.js +2 -2
  36. package/dist/{useAgentTrackRecord-BLf1nrbu.d.cts → useAgentTrackRecord-BCvRHYM2.d.cts} +7 -7
  37. package/dist/{useAgentTrackRecord-BLf1nrbu.d.ts → useAgentTrackRecord-BCvRHYM2.d.ts} +7 -7
  38. package/package.json +4 -3
  39. package/src/components/HireButton.tsx +1 -2
  40. package/src/components/HireCheckoutModal.tsx +8 -9
  41. package/src/components/ProviderCard.stories.tsx +54 -4
  42. package/src/components/ProviderCard.tsx +113 -9
  43. package/src/components/ReferrerDisclosure.tsx +8 -12
  44. package/src/components/__fixtures__/index.tsx +28 -0
  45. package/src/components/agenc-components.css +20 -0
  46. package/src/components/index.ts +12 -0
  47. package/src/components/strings.ts +10 -2
  48. package/src/components/useAgentVerification.ts +223 -0
  49. package/src/hooks/index.ts +47 -4
  50. package/src/hooks/internal.ts +74 -2
  51. package/src/hooks/useHire.ts +30 -38
  52. package/src/hooks/useHumanlessHireFlow.ts +259 -0
  53. package/src/hooks/useRateHire.ts +52 -0
  54. package/src/hooks/useReferrerEarnings.ts +32 -33
  55. package/src/hooks/useTaskActivation.ts +58 -0
  56. package/src/hooks/useTaskLifecycle.ts +110 -0
  57. package/src/hooks/useTaskWork.ts +76 -0
  58. package/src/index.ts +12 -2
  59. package/src/provider/AgencProvider.tsx +3 -3
  60. package/src/provider/referrer.ts +24 -32
  61. package/src/strings/index.ts +5 -3
  62. package/src/types.ts +7 -10
  63. package/dist/chunk-GN5DYVN5.js.map +0 -1
  64. package/dist/chunk-KJMR6OGC.js.map +0 -1
  65. package/dist/chunk-YORZNYZZ.js.map +0 -1
@@ -1,13 +1,18 @@
1
1
  /**
2
- * Ladle stories for {@link ProviderCard} — verified / provisional rates /
3
- * no-data / loading / unsupported-transport error + {@link PoweredByAgenC}.
2
+ * Ladle stories for {@link ProviderCard} — the P7.3(3) trust surface
3
+ * (on-chain VERIFIED domain vs merely-CLAIMED operator domain vs unverified) +
4
+ * provisional rates / no-data / loading / unsupported-transport error +
5
+ * {@link PoweredByAgenC}.
4
6
  */
5
7
  import type { Story } from "@ladle/react";
6
8
  import { ProviderCard } from "./ProviderCard.js";
7
9
  import { PoweredByAgenC } from "./PoweredByAgenC.js";
8
10
  import {
9
11
  FIXTURE_AGENT,
12
+ FIXTURE_VERIFIED_DOMAIN,
10
13
  makeTrackRecord,
14
+ makeUnverified,
15
+ makeVerified,
11
16
  } from "./__fixtures__/index.js";
12
17
  import { ReadTransportUnsupportedError } from "../transport/index.js";
13
18
 
@@ -15,16 +20,51 @@ export default {
15
20
  title: "Provider / ProviderCard",
16
21
  };
17
22
 
23
+ /** Live on-chain verification → the success "Verified: <domain>" badge. */
18
24
  export const Verified: Story = () => (
19
25
  <ProviderCard
20
26
  agent={FIXTURE_AGENT}
21
27
  trackRecord={makeTrackRecord()}
22
- verified
28
+ verification={makeVerified()}
29
+ operatorDomain={FIXTURE_VERIFIED_DOMAIN}
23
30
  />
24
31
  );
25
32
 
33
+ /**
34
+ * A provider that CLAIMS a domain in its metadata but has NO on-chain
35
+ * verification — renders the distinct, neutral "Claims: <domain>" pill and the
36
+ * Unverified badge. Never reads as verified.
37
+ */
38
+ export const ClaimedOnly: Story = () => (
39
+ <ProviderCard
40
+ agent={FIXTURE_AGENT}
41
+ trackRecord={makeTrackRecord()}
42
+ verification={makeUnverified()}
43
+ operatorDomain="totally-real-agents.example"
44
+ />
45
+ );
46
+
47
+ /** No verification and no claimed domain → just the Unverified badge. */
26
48
  export const Unverified: Story = () => (
27
- <ProviderCard agent={FIXTURE_AGENT} trackRecord={makeTrackRecord()} />
49
+ <ProviderCard
50
+ agent={FIXTURE_AGENT}
51
+ trackRecord={makeTrackRecord()}
52
+ verification={makeUnverified()}
53
+ />
54
+ );
55
+
56
+ /**
57
+ * A REVOKED on-chain record — `useAgentVerification` resolves this to
58
+ * `{ verified: false }`, so the card shows the claimed pill (if any) + the
59
+ * Unverified badge, never the verified domain.
60
+ */
61
+ export const RevokedClaimsDomain: Story = () => (
62
+ <ProviderCard
63
+ agent={FIXTURE_AGENT}
64
+ trackRecord={makeTrackRecord()}
65
+ verification={makeUnverified()}
66
+ operatorDomain={FIXTURE_VERIFIED_DOMAIN}
67
+ />
28
68
  );
29
69
 
30
70
  export const NullRates: Story = () => (
@@ -56,6 +96,16 @@ export const Unsupported: Story = () => (
56
96
  />
57
97
  );
58
98
 
99
+ export const Unstyled: Story = () => (
100
+ <ProviderCard
101
+ agent={FIXTURE_AGENT}
102
+ trackRecord={makeTrackRecord()}
103
+ verification={makeVerified()}
104
+ operatorDomain={FIXTURE_VERIFIED_DOMAIN}
105
+ unstyled
106
+ />
107
+ );
108
+
59
109
  export const PoweredBy: Story = () => <PoweredByAgenC />;
60
110
 
61
111
  export const PoweredByUnstyled: Story = () => <PoweredByAgenC unstyled />;
@@ -1,11 +1,26 @@
1
1
  /**
2
- * `<ProviderCard>` — a provider's reputation summary.
2
+ * `<ProviderCard>` — a provider's reputation + trust summary.
3
3
  *
4
4
  * Renders the agent's track record (completion rate, dispute rate, completions,
5
- * dispute count, slash history count) plus a verified badge. Presentational: it
6
- * takes the projected `AgentTrackRecord | null` (from
7
- * `useAgentTrackRecord().trackRecord`) + loading/error, so it renders under SSR
8
- * and in Ladle.
5
+ * dispute count) plus an on-chain VERIFIED badge and the operator domain.
6
+ * Presentational: it takes the projected `AgentTrackRecord | null` (from
7
+ * `useAgentTrackRecord().trackRecord`) and the resolved
8
+ * `AgentVerificationResult` (from `useAgentVerification().verification`) +
9
+ * loading/error, so it renders under SSR and in Ladle.
10
+ *
11
+ * ## P7.3(3) claimed vs verified — the trust distinction
12
+ *
13
+ * The provider may CLAIM an `operatorDomain` in its agent metadata; that is
14
+ * self-reported and unproven. The trust signal is the on-chain
15
+ * `AgentVerification` PDA, written by a trusted attestor only after the operator
16
+ * PROVED domain control. This card NEVER conflates the two:
17
+ * - a live verification (`verification.verified === true`) renders a "Verified:
18
+ * <domain>" badge using the ON-CHAIN `verification.domain` (a success pill);
19
+ * - otherwise, the merely-CLAIMED `operatorDomain` (when supplied) renders as a
20
+ * visibly distinct "Claims: <domain>" pill — never styled or labelled as
21
+ * verified.
22
+ * An unverified claimed domain therefore can never read as verified, even when
23
+ * the claimed string happens to equal a domain someone else verified.
9
24
  *
10
25
  * ## P6.6 honesty
11
26
  *
@@ -20,7 +35,9 @@ import type { AgentTrackRecord } from "../hooks/useAgentTrackRecord.js";
20
35
  import type { Address } from "../types.js";
21
36
  import { formatRate, tc, truncateAddress } from "./format.js";
22
37
  import { VerifiedBadge } from "./badges.js";
23
- import { StateMessage, rootClass, type ThemableProps } from "./primitives.js";
38
+ import { Badge, StateMessage, rootClass, type ThemableProps } from "./primitives.js";
39
+ import type { AgentVerificationResult } from "./useAgentVerification.js";
40
+ import { UNVERIFIED } from "./useAgentVerification.js";
24
41
 
25
42
  /** Props for {@link ProviderCard}. */
26
43
  export interface ProviderCardProps extends ThemableProps {
@@ -28,7 +45,24 @@ export interface ProviderCardProps extends ThemableProps {
28
45
  agent?: Address | string | null;
29
46
  /** The projected track record (from `useAgentTrackRecord().trackRecord`). */
30
47
  trackRecord: AgentTrackRecord | null;
31
- /** Whether the provider is verified (shows the verified badge). */
48
+ /**
49
+ * The resolved ON-CHAIN verification (from
50
+ * `useAgentVerification().verification`). Defaults to the unverified result,
51
+ * so omitting it renders the provider as NOT verified — verified state is
52
+ * opt-in and only ever driven by a live attestation.
53
+ */
54
+ verification?: AgentVerificationResult;
55
+ /**
56
+ * The provider's CLAIMED operator domain (from agent metadata). Self-reported
57
+ * and UNPROVEN — shown as a clearly-distinct "claimed" pill, and only when no
58
+ * on-chain verification supersedes it. Never rendered as verified.
59
+ */
60
+ operatorDomain?: string | null;
61
+ /**
62
+ * Deprecated boolean verified flag (pre-P7.3). When `verification` is omitted,
63
+ * a `true` here still shows the legacy verified badge, but WITHOUT a domain
64
+ * (no on-chain domain is available from a bare boolean). Prefer `verification`.
65
+ */
32
66
  verified?: boolean;
33
67
  /** True while loading the track record. */
34
68
  isLoading?: boolean;
@@ -42,11 +76,61 @@ export interface ProviderCardProps extends ThemableProps {
42
76
  }
43
77
 
44
78
  /**
45
- * Render a provider reputation card.
79
+ * The on-chain verified-domain pill: a success-tone badge carrying the PROVEN
80
+ * domain. Distinct copy + an accessible label that names it as on-chain
81
+ * verified.
82
+ */
83
+ function VerifiedDomainBadge({
84
+ domain,
85
+ unstyled,
86
+ }: {
87
+ domain: string;
88
+ unstyled?: boolean;
89
+ }): ReactNode {
90
+ return (
91
+ <Badge
92
+ tone="success"
93
+ unstyled={unstyled}
94
+ className={unstyled ? undefined : "agenc-provider__domain agenc-provider__domain--verified"}
95
+ label={tc("components.provider.verifiedDomainLabel", { domain })}
96
+ >
97
+ {tc("components.provider.verifiedDomain", { domain })}
98
+ </Badge>
99
+ );
100
+ }
101
+
102
+ /**
103
+ * The CLAIMED-domain pill: a neutral-tone badge whose copy ("Claims: …") and
104
+ * accessible label both mark it as unverified, so it can never be mistaken for
105
+ * the on-chain verified badge.
106
+ */
107
+ function ClaimedDomainBadge({
108
+ domain,
109
+ unstyled,
110
+ }: {
111
+ domain: string;
112
+ unstyled?: boolean;
113
+ }): ReactNode {
114
+ return (
115
+ <Badge
116
+ tone="neutral"
117
+ unstyled={unstyled}
118
+ className={unstyled ? undefined : "agenc-provider__domain agenc-provider__domain--claimed"}
119
+ label={tc("components.provider.claimedDomainLabel", { domain })}
120
+ >
121
+ {tc("components.provider.claimedDomain", { domain })}
122
+ </Badge>
123
+ );
124
+ }
125
+
126
+ /**
127
+ * Render a provider reputation + trust card.
46
128
  */
47
129
  export function ProviderCard({
48
130
  agent,
49
131
  trackRecord,
132
+ verification = UNVERIFIED,
133
+ operatorDomain,
50
134
  verified = false,
51
135
  isLoading = false,
52
136
  error = null,
@@ -56,6 +140,23 @@ export function ProviderCard({
56
140
  }: ProviderCardProps): ReactNode {
57
141
  const cardClass = rootClass("agenc-provider", unstyled, className);
58
142
 
143
+ // Verified state is on-chain-driven. The legacy `verified` boolean is honored
144
+ // ONLY as a fallback when no `verification` is supplied (it carries no domain).
145
+ const isVerified = verification.verified || (verification === UNVERIFIED && verified);
146
+ const verifiedDomain = verification.verified ? verification.domain : null;
147
+ const claimed =
148
+ typeof operatorDomain === "string" && operatorDomain.trim() !== ""
149
+ ? operatorDomain.trim()
150
+ : null;
151
+
152
+ // The on-chain verified domain supersedes any claim; the claimed pill only
153
+ // shows when there is NO live verified domain to display.
154
+ const domainBadge = verifiedDomain ? (
155
+ <VerifiedDomainBadge domain={verifiedDomain} unstyled={unstyled} />
156
+ ) : claimed ? (
157
+ <ClaimedDomainBadge domain={claimed} unstyled={unstyled} />
158
+ ) : null;
159
+
59
160
  const header = (
60
161
  <header className={unstyled ? undefined : "agenc-provider__header"}>
61
162
  <div className={unstyled ? undefined : "agenc-provider__id"}>
@@ -68,7 +169,10 @@ export function ProviderCard({
68
169
  </span>
69
170
  ) : null}
70
171
  </div>
71
- <VerifiedBadge verified={verified} unstyled={unstyled} />
172
+ <div className={unstyled ? undefined : "agenc-provider__badges"}>
173
+ {domainBadge}
174
+ <VerifiedBadge verified={isVerified} unstyled={unstyled} />
175
+ </div>
72
176
  </header>
73
177
  );
74
178
 
@@ -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,
@@ -23,6 +23,7 @@ import type {
23
23
  } from "../../types.js";
24
24
  import type { ListingCardData } from "../ListingCard.js";
25
25
  import type { AgentTrackRecord } from "../../hooks/useAgentTrackRecord.js";
26
+ import type { AgentVerificationResult } from "../useAgentVerification.js";
26
27
 
27
28
  /** A stable provider-agent PDA for fixtures. */
28
29
  export const FIXTURE_AGENT = address(
@@ -122,6 +123,33 @@ export function makeTrackRecord(
122
123
  };
123
124
  }
124
125
 
126
+ /** The verified operator domain used across the verification fixtures. */
127
+ export const FIXTURE_VERIFIED_DOMAIN = "acme-agents.example";
128
+
129
+ /**
130
+ * A live (verified, non-revoked, non-expired) verification result fixture.
131
+ * Overrides are shallow-merged onto the verified shape.
132
+ */
133
+ export function makeVerified(
134
+ overrides: Partial<Extract<AgentVerificationResult, { verified: true }>> = {},
135
+ ): AgentVerificationResult {
136
+ return {
137
+ verified: true,
138
+ domain: FIXTURE_VERIFIED_DOMAIN,
139
+ method: 0,
140
+ verifiedBy: FIXTURE_AGENT,
141
+ verifiedAt: 1_700_000_000n,
142
+ expiresAt: 0n,
143
+ revoked: false,
144
+ ...overrides,
145
+ };
146
+ }
147
+
148
+ /** The unverified result fixture (account absent / revoked / expired). */
149
+ export function makeUnverified(): AgentVerificationResult {
150
+ return { verified: false };
151
+ }
152
+
125
153
  /** A no-op read transport for provider-wrapped stories. */
126
154
  export function fixtureReadTransport(): ReadTransport {
127
155
  return {
@@ -547,6 +547,26 @@
547
547
  font-weight: 400;
548
548
  color: var(--agenc-text-dim, #6e5c8f);
549
549
  }
550
+ .agenc-provider__badges {
551
+ display: flex;
552
+ flex-wrap: wrap;
553
+ align-items: center;
554
+ justify-content: flex-end;
555
+ gap: var(--agenc-space-2, 8px);
556
+ }
557
+ /* The on-chain VERIFIED domain pill (success tone, from .agenc-badge--success);
558
+ the CLAIMED pill stays neutral + visually quieter so the two never read alike. */
559
+ .agenc-provider__domain {
560
+ max-width: 22ch;
561
+ overflow: hidden;
562
+ text-overflow: ellipsis;
563
+ white-space: nowrap;
564
+ }
565
+ .agenc-provider__domain--claimed {
566
+ font-style: italic;
567
+ color: var(--agenc-text-dim, #6e5c8f);
568
+ border-color: var(--agenc-border, #2e1a4a);
569
+ }
550
570
 
551
571
  /* --- PoweredByAgenC ---------------------------------------------------------*/
552
572
  .agenc-powered-by {
@@ -95,6 +95,18 @@ export { DisputeBanner, type DisputeBannerProps } from "./DisputeBanner.js";
95
95
 
96
96
  // Reputation + attribution.
97
97
  export { ProviderCard, type ProviderCardProps } from "./ProviderCard.js";
98
+ export {
99
+ UNVERIFIED,
100
+ agentVerificationReaderFromRpc,
101
+ evaluateAgentVerification,
102
+ useAgentVerification,
103
+ type AgentVerificationReader,
104
+ type AgentVerificationReaderOptions,
105
+ type AgentVerificationResult,
106
+ type AgentVerificationRpc,
107
+ type UseAgentVerificationOptions,
108
+ type UseAgentVerificationResult,
109
+ } from "./useAgentVerification.js";
98
110
  export {
99
111
  PoweredByAgenC,
100
112
  DEFAULT_TRUST_HREF,
@@ -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.
@@ -111,6 +111,14 @@ export const EN_COMPONENT_STRINGS = {
111
111
  "components.provider.noData": "No track record yet.",
112
112
  "components.provider.unavailable":
113
113
  "Track record is unavailable on this read transport.",
114
+ // Domain trust (P7.3) — VERIFIED is an on-chain attestation; CLAIMED is the
115
+ // operator's self-reported metadata. The copy keeps them distinct so a buyer
116
+ // never reads an unverified claim as a proven one.
117
+ "components.provider.verifiedDomain": "Verified: {domain}",
118
+ "components.provider.verifiedDomainLabel": "Verified domain {domain}",
119
+ "components.provider.claimedDomain": "Claims: {domain}",
120
+ "components.provider.claimedDomainLabel":
121
+ "Claimed domain {domain} (not verified on-chain)",
114
122
 
115
123
  // PoweredByAgenC.
116
124
  "components.poweredBy.label": "Powered by AgenC",
@@ -0,0 +1,223 @@
1
+ /**
2
+ * `useAgentVerification(agentPda, { reader })` — resolve the ON-CHAIN agent
3
+ * verification (P7.3) for a provider.
4
+ *
5
+ * ## Claimed vs verified — the load-bearing distinction
6
+ *
7
+ * A provider's `operatorDomain` from its agent metadata is a CLAIM: the operator
8
+ * typed it; nobody checked it. The trust signal is the on-chain
9
+ * `AgentVerification` PDA (`["agent_verification", agent]`), written by a trusted
10
+ * attestor only after the operator PROVED domain control (DNS `TXT` /
11
+ * `.well-known` + a signed challenge). This module reads THAT account and never
12
+ * conflates the two: a merely-claimed domain resolves to `{ verified: false }`.
13
+ *
14
+ * A verification counts as LIVE only when the account exists AND is not revoked
15
+ * AND has not expired (`expiresAt === 0n` means no expiry). See
16
+ * {@link evaluateAgentVerification}.
17
+ *
18
+ * ## Read path (no `ReadTransport` coupling)
19
+ *
20
+ * The package's indexer/gPA `ReadTransport` has no single-account fetch seam, so
21
+ * this hook reads through an injected `reader` (an `AgentVerificationReader`).
22
+ * The SDK ships the pieces a host wires into one — `findAgentVerificationPda`
23
+ * (the `["agent_verification", agent]` PDA) + `fetchMaybeAgentVerification` (the
24
+ * regenerated decoder) — and {@link agentVerificationReaderFromRpc} assembles
25
+ * exactly that against a kit RPC. Storefront P3 may instead surface a resolved
26
+ * `verified`/`verifiedDomain` on its track-record endpoint; either way the hook
27
+ * consumes the SAME pinned {@link AgentVerificationResult} shape.
28
+ *
29
+ * SSR-safe: pure module, no `window`/`document`, no module-scope side effects.
30
+ * The optional `now` injection keeps the expiry evaluation deterministic in
31
+ * tests and stable across an SSR/CSR boundary.
32
+ *
33
+ * @module components/useAgentVerification
34
+ */
35
+ import { useQuery } from "@tanstack/react-query";
36
+ import {
37
+ findAgentVerificationPda,
38
+ fetchMaybeAgentVerification,
39
+ type AgentVerification,
40
+ } from "@tetsuo-ai/marketplace-sdk";
41
+ import type { Address } from "../types.js";
42
+
43
+ /**
44
+ * The decoded, projected verification result for an agent — the PINNED P7.3(3)
45
+ * shape. When no live verification exists this is `{ verified: false }` (the
46
+ * narrow "absent / revoked / expired" case); otherwise every field is present
47
+ * and `verified` is `true`.
48
+ */
49
+ export type AgentVerificationResult =
50
+ | {
51
+ /** A live, on-chain, non-revoked, non-expired verification exists. */
52
+ verified: true;
53
+ /** The on-chain VERIFIED operator domain (proven, not self-claimed). */
54
+ domain: string;
55
+ /** Proof method: `0` = DNS `TXT`, `1` = `.well-known` over HTTPS. */
56
+ method: number;
57
+ /** The attestor/authority that recorded this verification. */
58
+ verifiedBy: Address | string;
59
+ /** Unix-seconds timestamp the verification was recorded. */
60
+ verifiedAt: bigint;
61
+ /** Unix-seconds expiry, or `0n` for no expiry. */
62
+ expiresAt: bigint;
63
+ /** Always `false` here (a revoked record is never `verified: true`). */
64
+ revoked: false;
65
+ }
66
+ | {
67
+ /** No live verification — account absent, revoked, or expired. */
68
+ verified: false;
69
+ };
70
+
71
+ /** The unverified sentinel (frozen so callers can compare identity cheaply). */
72
+ export const UNVERIFIED: AgentVerificationResult = Object.freeze({
73
+ verified: false,
74
+ });
75
+
76
+ /**
77
+ * Decide whether a decoded `AgentVerification` account is a LIVE verification:
78
+ * it must NOT be revoked AND must not be expired (`expiresAt === 0n` = no
79
+ * expiry; otherwise `nowSeconds < expiresAt`). Pure + exported so structural
80
+ * tests assert the revoked/expired/absent boundaries directly.
81
+ *
82
+ * @param account - The decoded account, or `null`/`undefined` when absent.
83
+ * @param nowSeconds - Current unix-seconds (injected for determinism).
84
+ */
85
+ export function evaluateAgentVerification(
86
+ account: AgentVerification | null | undefined,
87
+ nowSeconds: bigint,
88
+ ): AgentVerificationResult {
89
+ if (!account) return UNVERIFIED;
90
+ if (account.revoked) return UNVERIFIED;
91
+ // expiresAt === 0 means "no expiry"; any positive value is a hard deadline.
92
+ if (account.expiresAt !== 0n && nowSeconds >= account.expiresAt) {
93
+ return UNVERIFIED;
94
+ }
95
+ return {
96
+ verified: true,
97
+ domain: account.verifiedDomain,
98
+ method: account.method,
99
+ verifiedBy: account.verifiedBy,
100
+ verifiedAt: account.verifiedAt,
101
+ expiresAt: account.expiresAt,
102
+ revoked: false,
103
+ };
104
+ }
105
+
106
+ /**
107
+ * A function that resolves the raw verification for an agent PDA to the pinned
108
+ * result shape. Injected so the hook stays decoupled from any specific read
109
+ * backend (kit RPC, the storefront track-record endpoint, a test stub).
110
+ */
111
+ export type AgentVerificationReader = (
112
+ agentPda: Address | string,
113
+ ) => Promise<AgentVerificationResult>;
114
+
115
+ /** The minimal kit-RPC surface {@link agentVerificationReaderFromRpc} needs. */
116
+ export type AgentVerificationRpc = Parameters<
117
+ typeof fetchMaybeAgentVerification
118
+ >[0];
119
+
120
+ /** Options for {@link agentVerificationReaderFromRpc}. */
121
+ export interface AgentVerificationReaderOptions {
122
+ /**
123
+ * Clock source (unix seconds) used to evaluate expiry. Defaults to
124
+ * `Date.now()`-derived; inject a fixed value in tests/SSR for determinism.
125
+ */
126
+ now?: () => bigint;
127
+ }
128
+
129
+ /** Default unix-seconds clock. */
130
+ function defaultNow(): bigint {
131
+ return BigInt(Math.floor(Date.now() / 1000));
132
+ }
133
+
134
+ /**
135
+ * Build an {@link AgentVerificationReader} over a kit RPC using the SDK's
136
+ * `findAgentVerificationPda` (the `["agent_verification", agent]` seed) +
137
+ * `fetchMaybeAgentVerification` (the regenerated decoder). An absent account
138
+ * yields `{ verified: false }` (never throws on absence).
139
+ *
140
+ * @param rpc - A kit RPC capable of `getAccountInfo` (what the SDK fetch needs).
141
+ * @param options - Optional `now` clock injection.
142
+ */
143
+ export function agentVerificationReaderFromRpc(
144
+ rpc: AgentVerificationRpc,
145
+ options?: AgentVerificationReaderOptions,
146
+ ): AgentVerificationReader {
147
+ const now = options?.now ?? defaultNow;
148
+ return async (agentPda) => {
149
+ const [pda] = await findAgentVerificationPda({ agent: agentPda as Address });
150
+ const maybe = await fetchMaybeAgentVerification(rpc, pda);
151
+ return evaluateAgentVerification(maybe.exists ? maybe.data : null, now());
152
+ };
153
+ }
154
+
155
+ /** Options for {@link useAgentVerification}. */
156
+ export interface UseAgentVerificationOptions {
157
+ /**
158
+ * The reader that resolves the on-chain verification. When omitted the hook
159
+ * is inert (returns the unverified result, never queries) — a host opts in by
160
+ * passing {@link agentVerificationReaderFromRpc} or a custom resolver.
161
+ */
162
+ reader?: AgentVerificationReader;
163
+ /** Disable the query. Default `true` when `agentPda` and a `reader` are set. */
164
+ enabled?: boolean;
165
+ }
166
+
167
+ /** Return value of {@link useAgentVerification}. */
168
+ export interface UseAgentVerificationResult {
169
+ /** The resolved verification (defaults to the unverified result). */
170
+ verification: AgentVerificationResult;
171
+ /** Convenience: `verification.verified`. */
172
+ verified: boolean;
173
+ /** True while the verification read is in flight. */
174
+ isLoading: boolean;
175
+ /** A read error, or `null`. A failed read is NEVER treated as verified. */
176
+ error: Error | null;
177
+ /** Force a refetch. */
178
+ refetch: () => void;
179
+ }
180
+
181
+ /**
182
+ * Read an agent's on-chain verification (P7.3) into the pinned result shape.
183
+ *
184
+ * Defensive by construction: with no `reader`, no resolved data, or a read
185
+ * error, the result is `{ verified: false }` — an agent is shown verified ONLY
186
+ * when a live on-chain attestation is actually read back. A self-claimed
187
+ * `operatorDomain` never reaches this hook.
188
+ *
189
+ * @param agentPda - The AgentRegistration PDA (falsy disables the hook).
190
+ * @param options - The `reader` to resolve with + an `enabled` override.
191
+ * @returns {@link UseAgentVerificationResult}.
192
+ */
193
+ export function useAgentVerification(
194
+ agentPda: Address | string | undefined | null,
195
+ options?: UseAgentVerificationOptions,
196
+ ): UseAgentVerificationResult {
197
+ const reader = options?.reader;
198
+ const enabled =
199
+ (options?.enabled ?? true) && Boolean(agentPda) && Boolean(reader);
200
+
201
+ const query = useQuery<AgentVerificationResult, Error>({
202
+ queryKey: ["agenc", "agentVerification", agentPda ? String(agentPda) : ""],
203
+ enabled,
204
+ queryFn: async () => {
205
+ // `enabled` guards reader/agentPda presence; assert for the type narrow.
206
+ return reader!(agentPda as Address | string);
207
+ },
208
+ });
209
+
210
+ // Fail CLOSED on error. react-query retains the last successful `query.data`
211
+ // across a failed refetch, so a stale `{ verified: true }` would otherwise
212
+ // outlive a transient RPC error (the exact case where an agent's on-chain
213
+ // verification may have just been revoked). An errored read is NEVER verified
214
+ // — drop the cached data and surface UNVERIFIED whenever `query.error` is set.
215
+ const verification = query.error ? UNVERIFIED : (query.data ?? UNVERIFIED);
216
+ return {
217
+ verification,
218
+ verified: verification.verified,
219
+ isLoading: query.isLoading && enabled,
220
+ error: query.error ?? null,
221
+ refetch: () => void query.refetch(),
222
+ };
223
+ }