@tetsuo-ai/marketplace-react 0.1.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.
- package/CHANGELOG.md +28 -0
- package/LICENSE +21 -0
- package/README.md +172 -0
- package/dist/chunk-5OTKSRHM.js +128 -0
- package/dist/chunk-5OTKSRHM.js.map +1 -0
- package/dist/chunk-ABS77JB2.js +94 -0
- package/dist/chunk-ABS77JB2.js.map +1 -0
- package/dist/chunk-GN5DYVN5.js +35 -0
- package/dist/chunk-GN5DYVN5.js.map +1 -0
- package/dist/chunk-KJMR6OGC.js +1198 -0
- package/dist/chunk-KJMR6OGC.js.map +1 -0
- package/dist/chunk-YORZNYZZ.js +107 -0
- package/dist/chunk-YORZNYZZ.js.map +1 -0
- package/dist/components/agenc-components.css +570 -0
- package/dist/components/index.cjs +1335 -0
- package/dist/components/index.cjs.map +1 -0
- package/dist/components/index.d.cts +5 -0
- package/dist/components/index.d.ts +5 -0
- package/dist/components/index.js +5 -0
- package/dist/components/index.js.map +1 -0
- package/dist/hooks/index.cjs +493 -0
- package/dist/hooks/index.cjs.map +1 -0
- package/dist/hooks/index.d.cts +294 -0
- package/dist/hooks/index.d.ts +294 -0
- package/dist/hooks/index.js +339 -0
- package/dist/hooks/index.js.map +1 -0
- package/dist/index-BLrlBVj-.d.cts +1129 -0
- package/dist/index-CKTYsNPH.d.ts +1129 -0
- package/dist/index.cjs +1690 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +235 -0
- package/dist/index.d.ts +235 -0
- package/dist/index.js +127 -0
- package/dist/index.js.map +1 -0
- package/dist/signers/index.cjs +166 -0
- package/dist/signers/index.cjs.map +1 -0
- package/dist/signers/index.d.cts +136 -0
- package/dist/signers/index.d.ts +136 -0
- package/dist/signers/index.js +4 -0
- package/dist/signers/index.js.map +1 -0
- package/dist/testing/index.cjs +62 -0
- package/dist/testing/index.cjs.map +1 -0
- package/dist/testing/index.d.cts +71 -0
- package/dist/testing/index.d.ts +71 -0
- package/dist/testing/index.js +60 -0
- package/dist/testing/index.js.map +1 -0
- package/dist/theme/agenc-tailwind-preset.cjs +184 -0
- package/dist/theme/agenc-tokens.css +132 -0
- package/dist/types-jvISR6bc.d.cts +135 -0
- package/dist/types-jvISR6bc.d.ts +135 -0
- package/dist/useAgentTrackRecord-BLf1nrbu.d.cts +249 -0
- package/dist/useAgentTrackRecord-BLf1nrbu.d.ts +249 -0
- package/package.json +139 -0
- package/src/components/DisputeBanner.stories.tsx +39 -0
- package/src/components/DisputeBanner.tsx +110 -0
- package/src/components/HireButton.stories.tsx +72 -0
- package/src/components/HireButton.tsx +151 -0
- package/src/components/HireCheckoutModal.stories.tsx +107 -0
- package/src/components/HireCheckoutModal.tsx +284 -0
- package/src/components/ListingCard.stories.tsx +55 -0
- package/src/components/ListingCard.tsx +148 -0
- package/src/components/ListingGrid.stories.tsx +44 -0
- package/src/components/ListingGrid.tsx +137 -0
- package/src/components/Modal.tsx +121 -0
- package/src/components/PoweredByAgenC.tsx +85 -0
- package/src/components/ProviderCard.stories.tsx +61 -0
- package/src/components/ProviderCard.tsx +154 -0
- package/src/components/ReferrerDisclosure.tsx +67 -0
- package/src/components/ReviewPanel.stories.tsx +65 -0
- package/src/components/ReviewPanel.tsx +141 -0
- package/src/components/TaskTimeline.stories.tsx +43 -0
- package/src/components/TaskTimeline.tsx +156 -0
- package/src/components/__fixtures__/index.tsx +173 -0
- package/src/components/agenc-components.css +570 -0
- package/src/components/badges.tsx +115 -0
- package/src/components/format.ts +150 -0
- package/src/components/index.ts +102 -0
- package/src/components/primitives.tsx +236 -0
- package/src/components/strings.ts +131 -0
- package/src/components/useFocusTrap.ts +122 -0
- package/src/hooks/index.ts +90 -0
- package/src/hooks/internal.ts +70 -0
- package/src/hooks/useAgentTrackRecord.ts +166 -0
- package/src/hooks/useDispute.ts +130 -0
- package/src/hooks/useHire.ts +198 -0
- package/src/hooks/useListing.ts +138 -0
- package/src/hooks/useListings.ts +133 -0
- package/src/hooks/useReferrerEarnings.ts +134 -0
- package/src/hooks/useSubmissionReview.ts +179 -0
- package/src/hooks/useTaskStatus.ts +192 -0
- package/src/hooks/useWalletSigner.ts +99 -0
- package/src/index.ts +170 -0
- package/src/provider/AgencProvider.tsx +169 -0
- package/src/provider/context.ts +35 -0
- package/src/provider/index.ts +17 -0
- package/src/provider/network.ts +68 -0
- package/src/provider/referrer.ts +97 -0
- package/src/signers/README.md +130 -0
- package/src/signers/embedded-wallet-mock.ts +158 -0
- package/src/signers/embedded-wallet.ts +64 -0
- package/src/signers/index.ts +48 -0
- package/src/signers/strings.ts +39 -0
- package/src/signers/types.ts +158 -0
- package/src/signers/wallet-account.ts +128 -0
- package/src/signers/wallet-adapter.ts +149 -0
- package/src/strings/index.ts +119 -0
- package/src/testing/index.ts +24 -0
- package/src/theme/agenc-tailwind-preset.cjs +184 -0
- package/src/theme/agenc-tokens.css +132 -0
- package/src/theme/index.ts +94 -0
- package/src/transport/index.ts +164 -0
- package/src/types.ts +224 -0
|
@@ -0,0 +1,198 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `useHire()` — the hire mutation hook (the embeddable money path).
|
|
3
|
+
*
|
|
4
|
+
* Drives `client.hireFromListing(...)` through the provider's write client and
|
|
5
|
+
* surfaces the resulting transaction signature + minted Task PDA. Typed
|
|
6
|
+
* `AgencError`s from the runtime client are surfaced UNTOUCHED in `error`.
|
|
7
|
+
*
|
|
8
|
+
* ## THE P6.2 REFERRER GATE (PLAN_2 §0, MANDATORY — read before editing)
|
|
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:
|
|
12
|
+
* - 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.
|
|
24
|
+
*
|
|
25
|
+
* @module hooks/useHire
|
|
26
|
+
*/
|
|
27
|
+
import { useMutation } from "@tanstack/react-query";
|
|
28
|
+
import { useCallback, useMemo } from "react";
|
|
29
|
+
import { facade, findTaskPda } from "@tetsuo-ai/marketplace-sdk";
|
|
30
|
+
import type { facade as facadeNs } from "@tetsuo-ai/marketplace-sdk";
|
|
31
|
+
import { useAgencContext } from "../provider/context.js";
|
|
32
|
+
import type { Address } from "../types.js";
|
|
33
|
+
import { requireClient } from "./internal.js";
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Input to a standard `hire(...)` — a buyer that has a registered marketplace
|
|
37
|
+
* agent (`creatorAgent`). This task settles on the HIRE COMPLETION path (the
|
|
38
|
+
* worker calls `complete_task`). This is the SDK `facade.hireFromListing` input
|
|
39
|
+
* MINUS the fee-payer signers, which default to the provider's write-client
|
|
40
|
+
* signer (authority == creator == buyer). Pass them only to override.
|
|
41
|
+
*
|
|
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.
|
|
44
|
+
*/
|
|
45
|
+
export type HireInput = Omit<
|
|
46
|
+
Parameters<typeof facadeNs.hireFromListing>[0],
|
|
47
|
+
"authority" | "creator"
|
|
48
|
+
> & {
|
|
49
|
+
/** Standard hire (default). */
|
|
50
|
+
humanless?: false;
|
|
51
|
+
/** Override the buyer authority signer (defaults to the client signer). */
|
|
52
|
+
authority?: Parameters<typeof facadeNs.hireFromListing>[0]["authority"];
|
|
53
|
+
/** Override the buyer/creator signer (defaults to the client signer). */
|
|
54
|
+
creator?: Parameters<typeof facadeNs.hireFromListing>[0]["creator"];
|
|
55
|
+
};
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* Input to a HUMANLESS `hire(...)` — a plain-wallet buyer with NO registered
|
|
59
|
+
* agent (the storefront-visitor path). The task is pinned to CreatorReview, so
|
|
60
|
+
* it settles via the BUYER REVIEW path (`useSubmissionReview` accept/reject) —
|
|
61
|
+
* the human reviews before funds release. This is the SDK
|
|
62
|
+
* `facade.hireFromListingHumanless` input minus the `creator` signer (defaulted
|
|
63
|
+
* to the client signer).
|
|
64
|
+
*/
|
|
65
|
+
export type HumanlessHireInput = Omit<
|
|
66
|
+
Parameters<typeof facadeNs.hireFromListingHumanless>[0],
|
|
67
|
+
"creator"
|
|
68
|
+
> & {
|
|
69
|
+
/** Discriminates the humanless storefront-visitor hire. */
|
|
70
|
+
humanless: true;
|
|
71
|
+
/** Override the buyer/creator signer (defaults to the client signer). */
|
|
72
|
+
creator?: Parameters<typeof facadeNs.hireFromListingHumanless>[0]["creator"];
|
|
73
|
+
};
|
|
74
|
+
|
|
75
|
+
/** The union of standard and humanless hire inputs. */
|
|
76
|
+
export type AnyHireInput = HireInput | HumanlessHireInput;
|
|
77
|
+
|
|
78
|
+
/** Lifecycle status of the hire mutation. */
|
|
79
|
+
export type HireStatus = "idle" | "pending" | "success" | "error";
|
|
80
|
+
|
|
81
|
+
/** Result of a settled hire. */
|
|
82
|
+
export interface HireResult {
|
|
83
|
+
/** The confirmed transaction signature. */
|
|
84
|
+
signature: string;
|
|
85
|
+
/** The minted Task PDA (derived from creator + taskId). */
|
|
86
|
+
taskPda: Address;
|
|
87
|
+
/**
|
|
88
|
+
* Whether a referrer fee leg was injected into THIS hire. Always `false`
|
|
89
|
+
* today (the P6.2 gate). Audit signal — never fabricated.
|
|
90
|
+
*/
|
|
91
|
+
referrerInjected: boolean;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
/** Return value of {@link useHire}. */
|
|
95
|
+
export interface UseHireResult {
|
|
96
|
+
/** Execute a hire. Resolves to {@link HireResult}; rejects with `AgencError`. */
|
|
97
|
+
hire: (input: AnyHireInput) => Promise<HireResult>;
|
|
98
|
+
/** Current mutation status. */
|
|
99
|
+
status: HireStatus;
|
|
100
|
+
/** The minted Task PDA from the last successful hire, or null. */
|
|
101
|
+
taskPda: Address | null;
|
|
102
|
+
/** The signature from the last successful hire, or null. */
|
|
103
|
+
signature: string | null;
|
|
104
|
+
/** The error from the last hire (typed `AgencError` untouched), or null. */
|
|
105
|
+
error: Error | null;
|
|
106
|
+
/** Whether a hire is currently in flight. */
|
|
107
|
+
isPending: boolean;
|
|
108
|
+
/** Reset the mutation back to idle. */
|
|
109
|
+
reset: () => void;
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/**
|
|
113
|
+
* The hire hook.
|
|
114
|
+
*
|
|
115
|
+
* @returns {@link UseHireResult}.
|
|
116
|
+
*
|
|
117
|
+
* @example
|
|
118
|
+
* ```tsx
|
|
119
|
+
* const { hire, status, taskPda, error } = useHire();
|
|
120
|
+
* await hire({
|
|
121
|
+
* listing, creatorAgent, taskId, expectedPrice: price, expectedVersion: 1n,
|
|
122
|
+
* listingSpecHash,
|
|
123
|
+
* });
|
|
124
|
+
* ```
|
|
125
|
+
*/
|
|
126
|
+
export function useHire(): UseHireResult {
|
|
127
|
+
const ctx = useAgencContext();
|
|
128
|
+
|
|
129
|
+
const mutation = useMutation<HireResult, Error, AnyHireInput>({
|
|
130
|
+
mutationFn: async (input: AnyHireInput): Promise<HireResult> => {
|
|
131
|
+
const client = requireClient(ctx.client);
|
|
132
|
+
|
|
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;
|
|
139
|
+
|
|
140
|
+
const creator = input.creator ?? client.signer;
|
|
141
|
+
let signature: string;
|
|
142
|
+
|
|
143
|
+
if (input.humanless === true) {
|
|
144
|
+
// Storefront-visitor hire: no creator agent; CreatorReview-pinned, so
|
|
145
|
+
// it settles via the buyer review path (useSubmissionReview).
|
|
146
|
+
const ix = await facade.hireFromListingHumanless({
|
|
147
|
+
...input,
|
|
148
|
+
creator,
|
|
149
|
+
// NOTE: P6.2 referrer fields would spread here under capability.live.
|
|
150
|
+
} as Parameters<typeof facadeNs.hireFromListingHumanless>[0]);
|
|
151
|
+
({ signature } = await client.send([ix]));
|
|
152
|
+
} else {
|
|
153
|
+
// Standard hire: authority == creator == buyer (the buyer has an agent).
|
|
154
|
+
const authority = input.authority ?? client.signer;
|
|
155
|
+
const result = await client.hireFromListing({
|
|
156
|
+
...input,
|
|
157
|
+
authority,
|
|
158
|
+
creator,
|
|
159
|
+
// NOTE: P6.2 referrer fields would spread here under capability.live.
|
|
160
|
+
} as Parameters<typeof facadeNs.hireFromListing>[0]);
|
|
161
|
+
signature = result.signature;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
// Derive the minted Task PDA from (creator, taskId).
|
|
165
|
+
const [taskPda] = await findTaskPda({
|
|
166
|
+
creator:
|
|
167
|
+
typeof creator === "object" && creator !== null && "address" in creator
|
|
168
|
+
? creator.address
|
|
169
|
+
: (creator as Address),
|
|
170
|
+
taskId: input.taskId,
|
|
171
|
+
});
|
|
172
|
+
|
|
173
|
+
return { signature, taskPda, referrerInjected };
|
|
174
|
+
},
|
|
175
|
+
});
|
|
176
|
+
|
|
177
|
+
const hire = useCallback(
|
|
178
|
+
(input: AnyHireInput) => mutation.mutateAsync(input),
|
|
179
|
+
[mutation],
|
|
180
|
+
);
|
|
181
|
+
|
|
182
|
+
const status: HireStatus = useMemo(() => {
|
|
183
|
+
if (mutation.isPending) return "pending";
|
|
184
|
+
if (mutation.isError) return "error";
|
|
185
|
+
if (mutation.isSuccess) return "success";
|
|
186
|
+
return "idle";
|
|
187
|
+
}, [mutation.isPending, mutation.isError, mutation.isSuccess]);
|
|
188
|
+
|
|
189
|
+
return {
|
|
190
|
+
hire,
|
|
191
|
+
status,
|
|
192
|
+
taskPda: mutation.data?.taskPda ?? null,
|
|
193
|
+
signature: mutation.data?.signature ?? null,
|
|
194
|
+
error: mutation.error ?? null,
|
|
195
|
+
isPending: mutation.isPending,
|
|
196
|
+
reset: mutation.reset,
|
|
197
|
+
};
|
|
198
|
+
}
|
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `useListing(pda)` — single-listing detail hook.
|
|
3
|
+
*
|
|
4
|
+
* Joins, in ONE cached query, the three things a listing detail / checkout view
|
|
5
|
+
* needs:
|
|
6
|
+
* - the decoded `ServiceListing` (via `read.getListing`);
|
|
7
|
+
* - the provider's track record (via `read.agentTrackRecord(providerAgent)`),
|
|
8
|
+
* keyed off the listing's `providerAgent` — indexer-native, so it is fetched
|
|
9
|
+
* only when the indexer backend is live and resolves to `null` under the gPA
|
|
10
|
+
* fallback (which has no trustless aggregated track record — the transport
|
|
11
|
+
* throws `ReadTransportUnsupportedError`, which the hook swallows to `null`
|
|
12
|
+
* rather than failing the whole join);
|
|
13
|
+
* - the moderation/attestation state (see the moderation note below).
|
|
14
|
+
*
|
|
15
|
+
* ## Moderation (v1 scope, honest)
|
|
16
|
+
*
|
|
17
|
+
* The read transport does not yet expose a dedicated listing-moderation read
|
|
18
|
+
* (the indexer's listing projection carries the pinned `specHash` but not an
|
|
19
|
+
* attestation verdict). So `moderation` is the listing's indexer projection when
|
|
20
|
+
* present (callers can read `indexer.metadataValid` / `metadataIssues` and the
|
|
21
|
+
* pinned `specHash`) and `null` under the gPA fallback. A dedicated attestation
|
|
22
|
+
* read lands when the indexer projects it; this hook's surface does not change.
|
|
23
|
+
*
|
|
24
|
+
* @module hooks/useListing
|
|
25
|
+
*/
|
|
26
|
+
import { useQuery } from "@tanstack/react-query";
|
|
27
|
+
import { useAgencContext } from "../provider/context.js";
|
|
28
|
+
import { ReadTransportUnsupportedError } from "../transport/index.js";
|
|
29
|
+
import type {
|
|
30
|
+
Address,
|
|
31
|
+
IndexerAgentTrackRecord,
|
|
32
|
+
IndexerListing,
|
|
33
|
+
ServiceListing,
|
|
34
|
+
} from "../types.js";
|
|
35
|
+
import { pdaKey, queryKeys } from "./internal.js";
|
|
36
|
+
|
|
37
|
+
/** The joined detail payload {@link useListing} resolves. */
|
|
38
|
+
export interface ListingDetail {
|
|
39
|
+
/** The listing PDA. */
|
|
40
|
+
address: Address;
|
|
41
|
+
/** The decoded on-chain `ServiceListing`. */
|
|
42
|
+
listing: ServiceListing;
|
|
43
|
+
/** The provider's agent PDA (`ServiceListing.providerAgent`). */
|
|
44
|
+
provider: Address;
|
|
45
|
+
/**
|
|
46
|
+
* The provider's indexer track record, or `null` when unavailable (the gPA
|
|
47
|
+
* fallback has no trustless aggregated equivalent).
|
|
48
|
+
*/
|
|
49
|
+
trackRecord: IndexerAgentTrackRecord | null;
|
|
50
|
+
/**
|
|
51
|
+
* The listing's indexer projection (carries `metadataValid`,
|
|
52
|
+
* `metadataIssues`, the pinned `specHash`), or `null` under the gPA fallback.
|
|
53
|
+
* The v1 read model does not yet project a standalone attestation verdict.
|
|
54
|
+
*/
|
|
55
|
+
moderation: IndexerListing | null;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
/** Options for {@link useListing}. */
|
|
59
|
+
export interface UseListingOptions {
|
|
60
|
+
/** Disable the query (no `pda` yet, etc.). Default `true` when `pda` is set. */
|
|
61
|
+
enabled?: boolean;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/** Return value of {@link useListing}. */
|
|
65
|
+
export interface UseListingResult {
|
|
66
|
+
/** The joined detail, or null until loaded. */
|
|
67
|
+
detail: ListingDetail | null;
|
|
68
|
+
/** The decoded listing, or null until loaded (convenience projection). */
|
|
69
|
+
listing: ServiceListing | null;
|
|
70
|
+
/** The provider agent PDA, or null until loaded. */
|
|
71
|
+
provider: Address | null;
|
|
72
|
+
/** The provider's track record, or null (unavailable / not yet loaded). */
|
|
73
|
+
trackRecord: IndexerAgentTrackRecord | null;
|
|
74
|
+
/** The listing's indexer/moderation projection, or null. */
|
|
75
|
+
moderation: IndexerListing | null;
|
|
76
|
+
/** True while loading. */
|
|
77
|
+
isLoading: boolean;
|
|
78
|
+
/** The error, or null. */
|
|
79
|
+
error: Error | null;
|
|
80
|
+
/** Force a refetch. */
|
|
81
|
+
refetch: () => void;
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Read one listing and join its provider track record + moderation projection.
|
|
86
|
+
*
|
|
87
|
+
* @param pda - The ServiceListing PDA (string or Address). When falsy the query
|
|
88
|
+
* is disabled.
|
|
89
|
+
* @param options - `enabled` override.
|
|
90
|
+
* @returns {@link UseListingResult}.
|
|
91
|
+
*/
|
|
92
|
+
export function useListing(
|
|
93
|
+
pda: Address | string | undefined | null,
|
|
94
|
+
options?: UseListingOptions,
|
|
95
|
+
): UseListingResult {
|
|
96
|
+
const { read } = useAgencContext();
|
|
97
|
+
const enabled = (options?.enabled ?? true) && Boolean(pda);
|
|
98
|
+
|
|
99
|
+
const query = useQuery<ListingDetail, Error>({
|
|
100
|
+
queryKey: queryKeys.listing(pda ? pdaKey(pda) : ""),
|
|
101
|
+
enabled,
|
|
102
|
+
queryFn: async () => {
|
|
103
|
+
// 1) The listing itself.
|
|
104
|
+
const result = await read.getListing(pda as Address | string);
|
|
105
|
+
const provider = result.account.providerAgent;
|
|
106
|
+
|
|
107
|
+
// 2) The provider's track record — indexer-native. Swallow the
|
|
108
|
+
// gPA-fallback "unsupported" rejection to null so the join still
|
|
109
|
+
// resolves the listing + moderation (degrade, don't fail).
|
|
110
|
+
let trackRecord: IndexerAgentTrackRecord | null = null;
|
|
111
|
+
try {
|
|
112
|
+
trackRecord = await read.agentTrackRecord(provider);
|
|
113
|
+
} catch (err) {
|
|
114
|
+
if (!(err instanceof ReadTransportUnsupportedError)) throw err;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
return {
|
|
118
|
+
address: result.address,
|
|
119
|
+
listing: result.account,
|
|
120
|
+
provider,
|
|
121
|
+
trackRecord,
|
|
122
|
+
moderation: result.indexer ?? null,
|
|
123
|
+
};
|
|
124
|
+
},
|
|
125
|
+
});
|
|
126
|
+
|
|
127
|
+
const detail = query.data ?? null;
|
|
128
|
+
return {
|
|
129
|
+
detail,
|
|
130
|
+
listing: detail?.listing ?? null,
|
|
131
|
+
provider: detail?.provider ?? null,
|
|
132
|
+
trackRecord: detail?.trackRecord ?? null,
|
|
133
|
+
moderation: detail?.moderation ?? null,
|
|
134
|
+
isLoading: query.isLoading,
|
|
135
|
+
error: query.error ?? null,
|
|
136
|
+
refetch: () => void query.refetch(),
|
|
137
|
+
};
|
|
138
|
+
}
|
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `useListings(filter?)` — the listing-grid read hook.
|
|
3
|
+
*
|
|
4
|
+
* Fetches active service listings through the provider's unified read transport
|
|
5
|
+
* (indexer-first, gPA fallback — the hook never branches on which is live) and
|
|
6
|
+
* caches them via TanStack Query. Filters (`provider`, `category`, `state`) are
|
|
7
|
+
* forwarded verbatim to the transport, which applies server-side memcmp filters
|
|
8
|
+
* (indexer/gPA) and the client-side state filter exactly as the SDK does.
|
|
9
|
+
*
|
|
10
|
+
* ## Pagination model (honest about the transport)
|
|
11
|
+
*
|
|
12
|
+
* The v1 read transport returns the FULL active-listing set in one call — there
|
|
13
|
+
* is no server cursor in either backend (the gPA path can't have one; the
|
|
14
|
+
* indexer's `listActiveListings` is a drop-in of it). So pagination here is a
|
|
15
|
+
* client-side WINDOW over the already-fetched array: `listings` grows by
|
|
16
|
+
* `pageSize` each time `fetchMore()` is called, `hasMore` reflects whether more
|
|
17
|
+
* rows remain in the fetched set. This keeps one network round-trip while still
|
|
18
|
+
* giving a grid an incremental-reveal API. When a future transport gains a
|
|
19
|
+
* cursor, `fetchMore` can swap to `fetchNextPage` without changing this
|
|
20
|
+
* surface.
|
|
21
|
+
*
|
|
22
|
+
* SSR-safe: no `window`/`document`; the query simply does not run until mounted
|
|
23
|
+
* if the host disables it.
|
|
24
|
+
*
|
|
25
|
+
* @module hooks/useListings
|
|
26
|
+
*/
|
|
27
|
+
import { useQuery } from "@tanstack/react-query";
|
|
28
|
+
import { useCallback, useMemo, useState } from "react";
|
|
29
|
+
import { useAgencContext } from "../provider/context.js";
|
|
30
|
+
import type {
|
|
31
|
+
DecodedProgramAccount,
|
|
32
|
+
ListActiveListingsOptions,
|
|
33
|
+
ServiceListing,
|
|
34
|
+
} from "../types.js";
|
|
35
|
+
import { queryKeys } from "./internal.js";
|
|
36
|
+
|
|
37
|
+
/** A decoded active listing row (address + decoded account). */
|
|
38
|
+
export type ListingRow = DecodedProgramAccount<ServiceListing>;
|
|
39
|
+
|
|
40
|
+
/** Filter for {@link useListings}. Mirrors the SDK's `ListActiveListingsOptions`. */
|
|
41
|
+
export type UseListingsFilter = ListActiveListingsOptions;
|
|
42
|
+
|
|
43
|
+
/** Options for {@link useListings}. */
|
|
44
|
+
export interface UseListingsOptions {
|
|
45
|
+
/** Rows revealed per page / per `fetchMore()` call. Default `12`. */
|
|
46
|
+
pageSize?: number;
|
|
47
|
+
/**
|
|
48
|
+
* Disable the query (e.g. until a filter is ready). When `false` the hook
|
|
49
|
+
* returns the idle state and makes no request. Default `true`.
|
|
50
|
+
*/
|
|
51
|
+
enabled?: boolean;
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** Return value of {@link useListings}. */
|
|
55
|
+
export interface UseListingsResult {
|
|
56
|
+
/** The currently-revealed window of listings (grows via `fetchMore`). */
|
|
57
|
+
listings: ListingRow[];
|
|
58
|
+
/** Total active listings the transport returned (the full fetched set). */
|
|
59
|
+
total: number;
|
|
60
|
+
/** True while the underlying fetch is in flight (first load / refetch). */
|
|
61
|
+
isLoading: boolean;
|
|
62
|
+
/** The fetch error (typed `AgencError` for on-chain failures), or null. */
|
|
63
|
+
error: Error | null;
|
|
64
|
+
/** Whether more rows remain in the fetched set to reveal. */
|
|
65
|
+
hasMore: boolean;
|
|
66
|
+
/** Reveal the next `pageSize` rows from the fetched set. No-op when exhausted. */
|
|
67
|
+
fetchMore: () => void;
|
|
68
|
+
/** Force a fresh fetch from the transport. */
|
|
69
|
+
refetch: () => void;
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
const DEFAULT_PAGE_SIZE = 12;
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Read active service listings for a grid.
|
|
76
|
+
*
|
|
77
|
+
* @param filter - Optional provider/category/state filter (SDK semantics).
|
|
78
|
+
* @param options - Page size + enabled flag.
|
|
79
|
+
* @returns {@link UseListingsResult}.
|
|
80
|
+
*
|
|
81
|
+
* @example
|
|
82
|
+
* ```tsx
|
|
83
|
+
* const { listings, isLoading, fetchMore, hasMore } = useListings({
|
|
84
|
+
* category: "code-generation",
|
|
85
|
+
* });
|
|
86
|
+
* ```
|
|
87
|
+
*/
|
|
88
|
+
export function useListings(
|
|
89
|
+
filter?: UseListingsFilter,
|
|
90
|
+
options?: UseListingsOptions,
|
|
91
|
+
): UseListingsResult {
|
|
92
|
+
const { read } = useAgencContext();
|
|
93
|
+
const pageSize = options?.pageSize ?? DEFAULT_PAGE_SIZE;
|
|
94
|
+
const enabled = options?.enabled ?? true;
|
|
95
|
+
|
|
96
|
+
const query = useQuery<ListingRow[], Error>({
|
|
97
|
+
queryKey: queryKeys.listings(filter),
|
|
98
|
+
queryFn: () => read.listActiveListings(filter),
|
|
99
|
+
enabled,
|
|
100
|
+
});
|
|
101
|
+
|
|
102
|
+
// Client-side reveal window. Reset to one page whenever the underlying data
|
|
103
|
+
// changes (new fetch / filter change resets the key, which remounts data).
|
|
104
|
+
const [visible, setVisible] = useState(pageSize);
|
|
105
|
+
|
|
106
|
+
const all = query.data ?? [];
|
|
107
|
+
// Clamp the window to [pageSize, all.length] so a filter change that shrinks
|
|
108
|
+
// the set never strands `visible` above the available rows.
|
|
109
|
+
const windowSize = Math.min(Math.max(visible, pageSize), all.length);
|
|
110
|
+
const listings = useMemo(
|
|
111
|
+
() => all.slice(0, windowSize),
|
|
112
|
+
[all, windowSize],
|
|
113
|
+
);
|
|
114
|
+
|
|
115
|
+
const fetchMore = useCallback(() => {
|
|
116
|
+
setVisible((current) => current + pageSize);
|
|
117
|
+
}, [pageSize]);
|
|
118
|
+
|
|
119
|
+
const refetch = useCallback(() => {
|
|
120
|
+
setVisible(pageSize);
|
|
121
|
+
void query.refetch();
|
|
122
|
+
}, [pageSize, query]);
|
|
123
|
+
|
|
124
|
+
return {
|
|
125
|
+
listings,
|
|
126
|
+
total: all.length,
|
|
127
|
+
isLoading: query.isLoading,
|
|
128
|
+
error: query.error ?? null,
|
|
129
|
+
hasMore: windowSize < all.length,
|
|
130
|
+
fetchMore,
|
|
131
|
+
refetch,
|
|
132
|
+
};
|
|
133
|
+
}
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `useReferrerEarnings(wallet)` — referrer earnings (STRICTLY P6.2-GATED).
|
|
3
|
+
*
|
|
4
|
+
* ## THE P6.2 GATE (PLAN_2 §0, MANDATORY — this hook is the canonical example)
|
|
5
|
+
*
|
|
6
|
+
* Referrer earnings depend on TWO unbuilt things:
|
|
7
|
+
* 1. the on-chain P6.2 referrer fields snapshotted on `HireRecord` (the 4th
|
|
8
|
+
* settlement leg), and
|
|
9
|
+
* 2. the off-chain `GET /api/explorer/referrers/:wallet/hires` indexer endpoint
|
|
10
|
+
* that aggregates them.
|
|
11
|
+
*
|
|
12
|
+
* NEITHER exists today. So this hook:
|
|
13
|
+
* - resolves `resolveReferrerCapability()` from context;
|
|
14
|
+
* - when `live === false` (ALWAYS, today): returns the documented not-live
|
|
15
|
+
* state `{ live: false, totalLamports: 0n, hires: [] }` and makes NO network
|
|
16
|
+
* request. It NEVER fabricates earnings and NEVER infers a non-zero total
|
|
17
|
+
* from anything.
|
|
18
|
+
* - the real fetch path is written but DEAD-CODE-GATED behind `capability.live`
|
|
19
|
+
* with a clear TODO, so when P6.2 + the endpoint land, only the gate flips —
|
|
20
|
+
* the surface does not change.
|
|
21
|
+
*
|
|
22
|
+
* @module hooks/useReferrerEarnings
|
|
23
|
+
*/
|
|
24
|
+
import { useQuery } from "@tanstack/react-query";
|
|
25
|
+
import { useAgencContext } from "../provider/context.js";
|
|
26
|
+
import { t } from "../strings/index.js";
|
|
27
|
+
import type { Address } from "../types.js";
|
|
28
|
+
import { pdaKey, queryKeys } from "./internal.js";
|
|
29
|
+
|
|
30
|
+
/** A single referral-earning hire (shape defined now; populated post-P6.2). */
|
|
31
|
+
export interface ReferrerHire {
|
|
32
|
+
/** The minted Task PDA of the referred hire. */
|
|
33
|
+
taskPda: string;
|
|
34
|
+
/** The HireRecord PDA carrying the snapshotted referrer fields. */
|
|
35
|
+
hireRecordPda: string;
|
|
36
|
+
/** Referral fee earned on this hire, in lamports. */
|
|
37
|
+
feeLamports: bigint;
|
|
38
|
+
/** Transaction signature of the hire. */
|
|
39
|
+
signature: string;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** Return value of {@link useReferrerEarnings}. */
|
|
43
|
+
export interface UseReferrerEarningsResult {
|
|
44
|
+
/**
|
|
45
|
+
* Whether referral settlement is live on this cluster. ALWAYS `false` today
|
|
46
|
+
* (the P6.2 gate). When false, the numbers below are the documented not-live
|
|
47
|
+
* zero state, not real data.
|
|
48
|
+
*/
|
|
49
|
+
live: boolean;
|
|
50
|
+
/** Total lamports earned. `0n` while not live (never fabricated). */
|
|
51
|
+
totalLamports: bigint;
|
|
52
|
+
/** Per-hire earnings. `[]` while not live. */
|
|
53
|
+
hires: ReferrerHire[];
|
|
54
|
+
/** True while a (post-P6.2) fetch is in flight. Always false today. */
|
|
55
|
+
isLoading: boolean;
|
|
56
|
+
/** The fetch error, or null. */
|
|
57
|
+
error: Error | null;
|
|
58
|
+
/**
|
|
59
|
+
* Human-readable reason the data is not live (the capability reason). Present
|
|
60
|
+
* while `live` is false.
|
|
61
|
+
*/
|
|
62
|
+
reason?: string;
|
|
63
|
+
/** Force a refetch (no-op while not live). */
|
|
64
|
+
refetch: () => void;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Read a referrer wallet's earnings.
|
|
69
|
+
*
|
|
70
|
+
* @param wallet - The referrer wallet (base58 / Address). Falsy disables the
|
|
71
|
+
* (future) fetch; the not-live state is still returned.
|
|
72
|
+
* @returns {@link UseReferrerEarningsResult} — the not-live zero state today.
|
|
73
|
+
*
|
|
74
|
+
* @example
|
|
75
|
+
* ```tsx
|
|
76
|
+
* const { live, totalLamports, hires, reason } = useReferrerEarnings(myWallet);
|
|
77
|
+
* // today: live === false, totalLamports === 0n, hires === []
|
|
78
|
+
* ```
|
|
79
|
+
*/
|
|
80
|
+
export function useReferrerEarnings(
|
|
81
|
+
wallet: Address | string | undefined | null,
|
|
82
|
+
): UseReferrerEarningsResult {
|
|
83
|
+
const ctx = useAgencContext();
|
|
84
|
+
const capability = ctx.resolveReferrerCapability();
|
|
85
|
+
|
|
86
|
+
// THE GATE: the query is enabled ONLY when referral settlement is live. Today
|
|
87
|
+
// `capability.live` is hardcoded false, so this query never runs and we
|
|
88
|
+
// return the not-live zero state below. NEVER remove this gate.
|
|
89
|
+
const enabled = capability.live && Boolean(wallet);
|
|
90
|
+
|
|
91
|
+
const query = useQuery<{ totalLamports: bigint; hires: ReferrerHire[] }, Error>(
|
|
92
|
+
{
|
|
93
|
+
queryKey: queryKeys.referrerEarnings(wallet ? pdaKey(wallet) : ""),
|
|
94
|
+
enabled,
|
|
95
|
+
queryFn: async () => {
|
|
96
|
+
// TODO(P6.2 / indexer): once the referrer fields exist on HireRecord
|
|
97
|
+
// AND the indexer exposes `GET /api/explorer/referrers/:wallet/hires`,
|
|
98
|
+
// fetch + sum here. Unreachable today because `enabled` is gated on
|
|
99
|
+
// `capability.live` (hardcoded false). Returning fabricated numbers
|
|
100
|
+
// here would violate PLAN_2 §0 — do not.
|
|
101
|
+
throw new Error(
|
|
102
|
+
"useReferrerEarnings: the P6.2 referrer earnings path is not " +
|
|
103
|
+
"deployed; this query must never run while capability.live is false.",
|
|
104
|
+
);
|
|
105
|
+
},
|
|
106
|
+
},
|
|
107
|
+
);
|
|
108
|
+
|
|
109
|
+
if (!capability.live) {
|
|
110
|
+
// The documented not-live state. Zeroes are HONEST (no data exists), not
|
|
111
|
+
// fabricated, and no request was made.
|
|
112
|
+
return {
|
|
113
|
+
live: false,
|
|
114
|
+
totalLamports: 0n,
|
|
115
|
+
hires: [],
|
|
116
|
+
isLoading: false,
|
|
117
|
+
error: null,
|
|
118
|
+
reason: capability.reason ?? t("referrer.notLiveReason"),
|
|
119
|
+
refetch: () => {
|
|
120
|
+
/* no-op while not live */
|
|
121
|
+
},
|
|
122
|
+
};
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
// --- Post-P6.2 path (currently unreachable; kept wired for the flip) ---
|
|
126
|
+
return {
|
|
127
|
+
live: true,
|
|
128
|
+
totalLamports: query.data?.totalLamports ?? 0n,
|
|
129
|
+
hires: query.data?.hires ?? [],
|
|
130
|
+
isLoading: query.isLoading,
|
|
131
|
+
error: query.error ?? null,
|
|
132
|
+
refetch: () => void query.refetch(),
|
|
133
|
+
};
|
|
134
|
+
}
|