@tetsuo-ai/marketplace-react 0.3.1 → 0.4.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 (44) hide show
  1. package/CHANGELOG.md +35 -0
  2. package/dist/{chunk-D2TDU3TJ.js → chunk-AKPPKMQ2.js} +3 -3
  3. package/dist/{chunk-D2TDU3TJ.js.map → chunk-AKPPKMQ2.js.map} +1 -1
  4. package/dist/{chunk-WJUVTFJ7.js → chunk-BNILOX3O.js} +4 -4
  5. package/dist/{chunk-WJUVTFJ7.js.map → chunk-BNILOX3O.js.map} +1 -1
  6. package/dist/{chunk-FAIRTAIB.js → chunk-BTAVED7S.js} +88 -5
  7. package/dist/chunk-BTAVED7S.js.map +1 -0
  8. package/dist/{chunk-ECU7HGO3.js → chunk-H6PJIDQR.js} +4 -3
  9. package/dist/chunk-H6PJIDQR.js.map +1 -0
  10. package/dist/{chunk-MNJ2EQDJ.js → chunk-ON6XR4XO.js} +3 -3
  11. package/dist/{chunk-MNJ2EQDJ.js.map → chunk-ON6XR4XO.js.map} +1 -1
  12. package/dist/components/index.cjs +57 -1
  13. package/dist/components/index.cjs.map +1 -1
  14. package/dist/components/index.d.cts +1 -1
  15. package/dist/components/index.d.ts +1 -1
  16. package/dist/components/index.js +3 -3
  17. package/dist/hooks/index.cjs +159 -48
  18. package/dist/hooks/index.cjs.map +1 -1
  19. package/dist/hooks/index.d.cts +20 -9
  20. package/dist/hooks/index.d.ts +20 -9
  21. package/dist/hooks/index.js +80 -53
  22. package/dist/hooks/index.js.map +1 -1
  23. package/dist/{index-DGq7M4mo.d.ts → index-DQ3Xovkq.d.ts} +8 -1
  24. package/dist/{index-CrEAPlme.d.cts → index-UxuvIlmD.d.cts} +8 -1
  25. package/dist/index.cjs +57 -1
  26. package/dist/index.cjs.map +1 -1
  27. package/dist/index.d.cts +2 -2
  28. package/dist/index.d.ts +2 -2
  29. package/dist/index.js +9 -8
  30. package/dist/index.js.map +1 -1
  31. package/dist/signers/index.cjs +2 -1
  32. package/dist/signers/index.cjs.map +1 -1
  33. package/dist/signers/index.js +2 -2
  34. package/package.json +2 -2
  35. package/src/hooks/moderation-attestor.ts +176 -57
  36. package/src/hooks/useHire.ts +27 -0
  37. package/src/hooks/useHumanlessHireFlow.ts +74 -17
  38. package/src/hooks/useReferrerEarnings.ts +73 -38
  39. package/src/hooks/useTaskActivation.ts +19 -13
  40. package/src/provider/AgencProvider.tsx +1 -0
  41. package/src/strings/index.ts +3 -1
  42. package/src/types.ts +6 -0
  43. package/dist/chunk-ECU7HGO3.js.map +0 -1
  44. package/dist/chunk-FAIRTAIB.js.map +0 -1
@@ -28,6 +28,10 @@ import {
28
28
  signerAddress,
29
29
  withoutReferrerArgs,
30
30
  } from "./internal.js";
31
+ import {
32
+ resolveHireListingModerationAccounts,
33
+ type HireListingModerationAccounts,
34
+ } from "./moderation-attestor.js";
31
35
 
32
36
  /**
33
37
  * Input to a standard `hire(...)` — a buyer that has a registered marketplace
@@ -132,6 +136,27 @@ export function useHire(): UseHireResult {
132
136
  const { referrerArgs, referrerInjected } = resolveReferrerArgs(ctx);
133
137
  const hireInput = withoutReferrerArgs(input);
134
138
 
139
+ // P1.2: the hire gate names an explicit `moderator` (the caller's trust
140
+ // decision) and needs the roster-entry PDA when that moderator is a
141
+ // registered attestor, plus a record override when the listing
142
+ // attestation predates the upgrade (legacy grace window). Resolve the
143
+ // mechanics automatically unless the caller supplied any of them.
144
+ const listingSpecHash = input.listingSpecHash;
145
+ let moderationArgs: HireListingModerationAccounts = {};
146
+ if (
147
+ input.moderationAttestor === undefined &&
148
+ input.moderatorIsAttestor === undefined &&
149
+ input.listingModeration === undefined &&
150
+ listingSpecHash !== undefined
151
+ ) {
152
+ moderationArgs = await resolveHireListingModerationAccounts({
153
+ rpcUrl: ctx.rpcUrl,
154
+ listing: input.listing,
155
+ listingSpecHash,
156
+ moderator: input.moderator,
157
+ });
158
+ }
159
+
135
160
  const creator = input.creator ?? client.signer;
136
161
  let signature: string;
137
162
 
@@ -140,6 +165,7 @@ export function useHire(): UseHireResult {
140
165
  // it settles via the buyer review path (useSubmissionReview).
141
166
  const result = await client.hireFromListingHumanless({
142
167
  ...hireInput,
168
+ ...moderationArgs,
143
169
  creator,
144
170
  ...referrerArgs,
145
171
  } as Parameters<typeof facadeNs.hireFromListingHumanless>[0]);
@@ -149,6 +175,7 @@ export function useHire(): UseHireResult {
149
175
  const authority = input.authority ?? client.signer;
150
176
  const result = await client.hireFromListing({
151
177
  ...hireInput,
178
+ ...moderationArgs,
152
179
  authority,
153
180
  creator,
154
181
  ...referrerArgs,
@@ -12,7 +12,11 @@ import {
12
12
  withoutReferrerArgs,
13
13
  type MutationStatus,
14
14
  } from "./internal.js";
15
- import { resolveActivationModerationAttestor } from "./moderation-attestor.js";
15
+ import {
16
+ resolveActivationModerationAccounts,
17
+ resolveHireListingModerationAccounts,
18
+ type HireListingModerationAccounts,
19
+ } from "./moderation-attestor.js";
16
20
  import type { HumanlessHireInput } from "./useHire.js";
17
21
  import type { TaskActivationInput } from "./useTaskActivation.js";
18
22
 
@@ -33,8 +37,15 @@ export type HumanlessHireFlowHireInput = Omit<
33
37
 
34
38
  export type HumanlessHireFlowActivationInput = Omit<
35
39
  TaskActivationInput,
36
- "creator" | "jobSpecHash" | "jobSpecUri"
37
- >;
40
+ "creator" | "jobSpecHash" | "jobSpecUri" | "moderator"
41
+ > & {
42
+ /**
43
+ * Override the activation `moderator` (P1.2). Defaults to the `moderator`
44
+ * returned by `hostAndModerateJobSpec` — the attestation service that
45
+ * signed the task moderation is whose record the publish gate consumes.
46
+ */
47
+ moderator?: TaskActivationInput["moderator"];
48
+ };
38
49
 
39
50
  export type HumanlessHireFlowCreator = HumanlessHireInput["creator"];
40
51
 
@@ -45,6 +56,12 @@ export interface HumanlessHireFlowModerationResult {
45
56
  jobSpecHash: HumanlessHireFlowJobSpecHash;
46
57
  jobSpecUri: string;
47
58
  moderationAttested: boolean;
59
+ /**
60
+ * The pubkey that signed/recorded the task attestation (P1.2) — the
61
+ * attestation service's signer (e.g. attest.agenc.ag `GET /v1/info` →
62
+ * `moderator`). Names whose record the publish gate consumes.
63
+ */
64
+ moderator: Address;
48
65
  moderation?: unknown;
49
66
  }
50
67
 
@@ -114,7 +131,11 @@ function emptyProgress(): HumanlessHireFlowProgress {
114
131
 
115
132
  function validateModerationResult(
116
133
  result: HumanlessHireFlowModerationResult,
117
- ): { jobSpecHash: HumanlessHireFlowJobSpecHash; jobSpecUri: string } {
134
+ ): {
135
+ jobSpecHash: HumanlessHireFlowJobSpecHash;
136
+ jobSpecUri: string;
137
+ moderator: Address;
138
+ } {
118
139
  if (result.moderationAttested !== true) {
119
140
  throw new Error(
120
141
  "Task moderation was not attested; activation was not signed.",
@@ -134,7 +155,16 @@ function validateModerationResult(
134
155
  "Task moderation returned an empty jobSpecUri; activation was not signed.",
135
156
  );
136
157
  }
137
- return { jobSpecHash: result.jobSpecHash, jobSpecUri };
158
+ if (typeof result.moderator !== "string" || !result.moderator.trim()) {
159
+ throw new Error(
160
+ "Task moderation returned no moderator pubkey; activation was not signed.",
161
+ );
162
+ }
163
+ return {
164
+ jobSpecHash: result.jobSpecHash,
165
+ jobSpecUri,
166
+ moderator: result.moderator,
167
+ };
138
168
  }
139
169
 
140
170
  export function useHumanlessHireFlow<TJobSpec = unknown>(): UseHumanlessHireFlowResult<TJobSpec> {
@@ -159,8 +189,26 @@ export function useHumanlessHireFlow<TJobSpec = unknown>(): UseHumanlessHireFlow
159
189
  setProgress(emptyProgress());
160
190
 
161
191
  try {
192
+ // P1.2: resolve the hire gate's moderation mechanics (roster PDA /
193
+ // legacy record override) unless the caller supplied any of them.
194
+ const hireListingSpecHash = input.hire.listingSpecHash;
195
+ let hireModerationArgs: HireListingModerationAccounts = {};
196
+ if (
197
+ input.hire.moderationAttestor === undefined &&
198
+ input.hire.moderatorIsAttestor === undefined &&
199
+ input.hire.listingModeration === undefined &&
200
+ hireListingSpecHash !== undefined
201
+ ) {
202
+ hireModerationArgs = await resolveHireListingModerationAccounts({
203
+ rpcUrl: ctx.rpcUrl,
204
+ listing: input.hire.listing,
205
+ listingSpecHash: hireListingSpecHash,
206
+ moderator: input.hire.moderator,
207
+ });
208
+ }
162
209
  const hireResult = await client.hireFromListingHumanless({
163
210
  ...hireInput,
211
+ ...hireModerationArgs,
164
212
  creator,
165
213
  ...referrerArgs,
166
214
  } as Parameters<typeof facadeNs.hireFromListingHumanless>[0]);
@@ -186,7 +234,8 @@ export function useHumanlessHireFlow<TJobSpec = unknown>(): UseHumanlessHireFlow
186
234
  hireSignature: hireResult.signature,
187
235
  referrerInjected,
188
236
  });
189
- const { jobSpecHash, jobSpecUri } = validateModerationResult(moderation);
237
+ const { jobSpecHash, jobSpecUri, moderator } =
238
+ validateModerationResult(moderation);
190
239
 
191
240
  setProgress((current) => ({
192
241
  ...current,
@@ -195,23 +244,31 @@ export function useHumanlessHireFlow<TJobSpec = unknown>(): UseHumanlessHireFlow
195
244
  }));
196
245
 
197
246
  setPhase("activating");
198
- // WP-A1: attach the roster-attestor account when the moderation was
199
- // authored by a roster attestor (e.g. the public attestation
200
- // service) — without it the publish gate rejects the activation.
201
- const moderationAttestor =
202
- input.activation?.moderationAttestor ??
203
- (await resolveActivationModerationAttestor({
204
- rpcUrl: ctx.rpcUrl,
205
- task: taskPda,
206
- jobSpecHash,
207
- }));
247
+ // P1.2: the publish gate consumes the record of the moderator that
248
+ // signed the attestation (the host callback's service by default).
249
+ // Resolve the gate mechanics (roster PDA / legacy record override)
250
+ // unless the caller supplied any of them.
251
+ const activationModerator = input.activation?.moderator ?? moderator;
252
+ const activationCallerResolved =
253
+ input.activation?.moderationAttestor !== undefined ||
254
+ input.activation?.moderatorIsAttestor !== undefined ||
255
+ input.activation?.taskModeration !== undefined;
256
+ const activationModerationArgs = activationCallerResolved
257
+ ? {}
258
+ : await resolveActivationModerationAccounts({
259
+ rpcUrl: ctx.rpcUrl,
260
+ task: taskPda,
261
+ jobSpecHash,
262
+ moderator: activationModerator,
263
+ });
208
264
  const activationResult = await client.setTaskJobSpec({
209
265
  ...(input.activation ?? {}),
210
- ...(moderationAttestor !== undefined ? { moderationAttestor } : {}),
266
+ ...activationModerationArgs,
211
267
  task: taskPda,
212
268
  creator,
213
269
  jobSpecHash,
214
270
  jobSpecUri,
271
+ moderator: activationModerator,
215
272
  } as Parameters<typeof facadeNs.setTaskJobSpec>[0]);
216
273
 
217
274
  const result: HumanlessHireFlowResult = {
@@ -1,32 +1,40 @@
1
1
  /**
2
- * `useReferrerEarnings(wallet)` — referrer earnings (indexer-gated).
2
+ * `useReferrerEarnings(wallet)` — aggregated referrer earnings (P3.8).
3
3
  *
4
- * ## EARNINGS INDEXER GATE
4
+ * ## Data source
5
5
  *
6
- * Referrer settlement is live in the protocol. Aggregated referrer earnings still
7
- * depend on the off-chain `GET /api/explorer/referrers/:wallet/hires` indexer
8
- * endpoint that sums paid referral events.
9
- *
10
- * That endpoint is not published yet. So this hook:
11
- * - resolves `resolveReferrerCapability()` from context;
12
- * - when the earnings indexer is not live: returns the documented not-live
13
- * state `{ live: false, totalLamports: 0n, hires: [] }` and makes NO network
14
- * request. It NEVER fabricates earnings and NEVER infers a non-zero total
15
- * from anything.
16
- * - the real fetch path is written but gated behind `EARNINGS_INDEXER_LIVE`, so
17
- * when the endpoint lands, only the gate flips — the surface does not change.
6
+ * `GET <earningsBase>/api/explorer/referrers/:wallet/hires` — the hosted
7
+ * explorer endpoint that sums the referrer leg over SETTLED hires with the
8
+ * program's own split math (shipped 2026-07-03; ground-truthed against the
9
+ * cross-node canary's on-chain legs). `earningsBase` resolves from
10
+ * `config.indexer.baseUrl` when set, else the per-network hosted default
11
+ * (mainnet only). When no base resolves (localnet/devnet without an indexer),
12
+ * the hook returns the documented not-live zero state and makes NO network
13
+ * request — it NEVER fabricates earnings; a fetch failure surfaces as
14
+ * `error` with zero totals, never invented numbers.
18
15
  *
19
16
  * @module hooks/useReferrerEarnings
20
17
  */
21
18
  import { useQuery } from "@tanstack/react-query";
22
19
  import { useAgencContext } from "../provider/context.js";
23
20
  import { t } from "../strings/index.js";
24
- import type { Address } from "../types.js";
21
+ import type { Address, AgencContextValue, AgencNetwork } from "../types.js";
25
22
  import { pdaKey, queryKeys } from "./internal.js";
26
23
 
27
- const EARNINGS_INDEXER_LIVE = false;
24
+ /**
25
+ * Hosted explorer bases serving the earnings endpoints, per network. Only
26
+ * mainnet has one today; an explicit `config.indexer.baseUrl` always wins.
27
+ */
28
+ const EARNINGS_INDEXER_DEFAULTS: Partial<Record<AgencNetwork, string>> = {
29
+ mainnet: "https://api.agenc.ag",
30
+ };
28
31
 
29
- /** A single referral-earning hire (shape defined now; populated once the earnings indexer ships). */
32
+ /** Resolve the earnings endpoint base, or `null` (not live) when none. */
33
+ function resolveEarningsBaseUrl(ctx: AgencContextValue): string | null {
34
+ return ctx.indexerBaseUrl ?? EARNINGS_INDEXER_DEFAULTS[ctx.network] ?? null;
35
+ }
36
+
37
+ /** A single referral-earning hire. */
30
38
  export interface ReferrerHire {
31
39
  /** The minted Task PDA of the referred hire. */
32
40
  taskPda: string;
@@ -34,7 +42,7 @@ export interface ReferrerHire {
34
42
  hireRecordPda: string;
35
43
  /** Referral fee earned on this hire, in lamports. */
36
44
  feeLamports: bigint;
37
- /** Transaction signature of the hire. */
45
+ /** Transaction signature of the hire (empty until event indexing lands). */
38
46
  signature: string;
39
47
  }
40
48
 
@@ -50,7 +58,7 @@ export interface UseReferrerEarningsResult {
50
58
  totalLamports: bigint;
51
59
  /** Per-hire earnings. `[]` while not live. */
52
60
  hires: ReferrerHire[];
53
- /** True while a fetch is in flight. Always false until the earnings indexer ships. */
61
+ /** True while a fetch is in flight. */
54
62
  isLoading: boolean;
55
63
  /** The fetch error, or null. */
56
64
  error: Error | null;
@@ -63,18 +71,27 @@ export interface UseReferrerEarningsResult {
63
71
  refetch: () => void;
64
72
  }
65
73
 
74
+ /** The endpoint's wire shape (lamports as decimal strings). */
75
+ interface EarningsWire {
76
+ totalLamports?: string;
77
+ hires?: Array<{
78
+ taskPda?: string;
79
+ hireRecordPda?: string;
80
+ feeLamports?: string;
81
+ signature?: string;
82
+ }>;
83
+ }
84
+
66
85
  /**
67
- * Read a referrer wallet's earnings.
86
+ * Read a referrer wallet's aggregated earnings from the hosted explorer.
68
87
  *
69
88
  * @param wallet - The referrer wallet (base58 / Address). Falsy disables the
70
- * (future) fetch; the not-live state is still returned.
71
- * @returns {@link UseReferrerEarningsResult} — the not-live zero state until
72
- * the earnings indexer ships.
89
+ * fetch; the not-live state is still returned.
90
+ * @returns {@link UseReferrerEarningsResult}
73
91
  *
74
92
  * @example
75
93
  * ```tsx
76
94
  * const { live, totalLamports, hires, reason } = useReferrerEarnings(myWallet);
77
- * // until the earnings indexer ships: live === false, totalLamports === 0n, hires === []
78
95
  * ```
79
96
  */
80
97
  export function useReferrerEarnings(
@@ -82,30 +99,49 @@ export function useReferrerEarnings(
82
99
  ): UseReferrerEarningsResult {
83
100
  const ctx = useAgencContext();
84
101
  const capability = ctx.resolveReferrerCapability();
102
+ const earningsBase = resolveEarningsBaseUrl(ctx);
85
103
 
86
- // THE GATE: settlement can be live while the aggregate earnings indexer is not.
87
- // Keep this false until the endpoint is published.
88
- const enabled = capability.live && EARNINGS_INDEXER_LIVE && Boolean(wallet);
104
+ // Live only when settlement capability holds AND an earnings endpoint base
105
+ // resolves. No base (localnet/devnet without an indexer) = the documented
106
+ // not-live zero state, zero network requests.
107
+ const enabled = capability.live && earningsBase !== null && Boolean(wallet);
89
108
 
90
109
  const query = useQuery<{ totalLamports: bigint; hires: ReferrerHire[] }, Error>(
91
110
  {
92
111
  queryKey: queryKeys.referrerEarnings(wallet ? pdaKey(wallet) : ""),
93
112
  enabled,
94
113
  queryFn: async () => {
95
- // TODO(indexer): once `GET /api/explorer/referrers/:wallet/hires` is
96
- // published, fetch + sum here. Returning fabricated numbers here would
97
- // violate the money-surface contract.
98
- throw new Error(
99
- "useReferrerEarnings: the referrer earnings indexer is not deployed; " +
100
- "this query must never run while EARNINGS_INDEXER_LIVE is false.",
101
- );
114
+ const url = `${earningsBase}/api/explorer/referrers/${encodeURIComponent(
115
+ String(wallet),
116
+ )}/hires`;
117
+ const response = await fetch(url, {
118
+ headers: { accept: "application/json" },
119
+ });
120
+ if (!response.ok) {
121
+ throw new Error(
122
+ t("referrer.earningsFetchFailed") + ` (HTTP ${response.status})`,
123
+ );
124
+ }
125
+ const body = (await response.json()) as EarningsWire;
126
+ // Lamports arrive as decimal strings; parse to bigint. Anything
127
+ // malformed throws (surfaces as `error`) — never silently coerced.
128
+ const hires: ReferrerHire[] = (body.hires ?? []).map((h) => ({
129
+ taskPda: String(h.taskPda ?? ""),
130
+ hireRecordPda: String(h.hireRecordPda ?? ""),
131
+ feeLamports: BigInt(h.feeLamports ?? "0"),
132
+ signature: String(h.signature ?? ""),
133
+ }));
134
+ return {
135
+ totalLamports: BigInt(body.totalLamports ?? "0"),
136
+ hires,
137
+ };
102
138
  },
103
139
  },
104
140
  );
105
141
 
106
- if (!capability.live || !EARNINGS_INDEXER_LIVE) {
107
- // The documented not-live state. Zeroes are HONEST (no data exists), not
108
- // fabricated, and no request was made.
142
+ if (!enabled) {
143
+ // The documented not-live state. Zeroes are HONEST (no data was read),
144
+ // not fabricated, and no request was made.
109
145
  return {
110
146
  live: false,
111
147
  totalLamports: 0n,
@@ -121,7 +157,6 @@ export function useReferrerEarnings(
121
157
  };
122
158
  }
123
159
 
124
- // --- Post-indexer path (currently unreachable; kept wired for the flip) ---
125
160
  return {
126
161
  live: true,
127
162
  totalLamports: query.data?.totalLamports ?? 0n,
@@ -7,7 +7,7 @@ import {
7
7
  requireClient,
8
8
  type MutationStatus,
9
9
  } from "./internal.js";
10
- import { resolveActivationModerationAttestor } from "./moderation-attestor.js";
10
+ import { resolveActivationModerationAccounts } from "./moderation-attestor.js";
11
11
 
12
12
  export type TaskActivationInput = Omit<
13
13
  Parameters<typeof facadeNs.setTaskJobSpec>[0],
@@ -34,20 +34,26 @@ export function useTaskActivation(
34
34
  const mutation = useMutation<string, Error, TaskActivationInput>({
35
35
  mutationFn: async (input) => {
36
36
  const client = requireClient(ctx.client);
37
- // WP-A1: when the task moderation was authored by a roster attestor
38
- // (not the global authority), the publish gate only unlocks if the
39
- // attestor's roster-entry PDA is attached. Resolve it automatically
40
- // unless the caller supplied one.
41
- const moderationAttestor =
42
- input.moderationAttestor ??
43
- (await resolveActivationModerationAttestor({
44
- rpcUrl: ctx.rpcUrl,
45
- task: taskPda,
46
- jobSpecHash: input.jobSpecHash,
47
- }));
37
+ // P1.2: the publish gate names an explicit `moderator` (supplied by the
38
+ // caller — the trust decision) and needs the roster-entry PDA when that
39
+ // moderator is a registered attestor, plus a record override when the
40
+ // attestation predates the upgrade (legacy grace window). Resolve the
41
+ // mechanics automatically unless the caller supplied any of them.
42
+ const callerResolved =
43
+ input.moderationAttestor !== undefined ||
44
+ input.moderatorIsAttestor !== undefined ||
45
+ input.taskModeration !== undefined;
46
+ const resolved = callerResolved
47
+ ? {}
48
+ : await resolveActivationModerationAccounts({
49
+ rpcUrl: ctx.rpcUrl,
50
+ task: taskPda,
51
+ jobSpecHash: input.jobSpecHash,
52
+ moderator: input.moderator,
53
+ });
48
54
  const { signature } = await client.setTaskJobSpec({
49
55
  ...input,
50
- ...(moderationAttestor !== undefined ? { moderationAttestor } : {}),
56
+ ...resolved,
51
57
  task: taskPda,
52
58
  creator: input.creator ?? client.signer,
53
59
  } as Parameters<typeof facadeNs.setTaskJobSpec>[0]);
@@ -164,6 +164,7 @@ export function AgencProvider(props: AgencProviderProps): ReactNode {
164
164
  read,
165
165
  client,
166
166
  rpcUrl: rpcUrl ?? null,
167
+ indexerBaseUrl: config.indexer?.baseUrl ?? null,
167
168
  signer: config.signer ?? null,
168
169
  referrer,
169
170
  resolveReferrerCapability: () => resolveReferrerCapabilityImpl(referrer),
@@ -51,7 +51,9 @@ export const EN_STRINGS = {
51
51
  "referrer.notLiveReason":
52
52
  "No referrer is configured for this provider.",
53
53
  "referrer.earningsNotLiveReason":
54
- "Referral settlement is live, but aggregated referrer earnings are not yet exposed by the indexer.",
54
+ "Referral settlement is live, but no earnings endpoint is available on this network (configure indexer.baseUrl).",
55
+ "referrer.earningsFetchFailed":
56
+ "The referrer earnings endpoint could not be read.",
55
57
 
56
58
  // Read transport.
57
59
  "transport.noReadSource":
package/src/types.ts CHANGED
@@ -205,6 +205,12 @@ export interface AgencContextValue {
205
205
  * activation. NOT a gPA/list-query source; the read transport owns those.
206
206
  */
207
207
  rpcUrl: string | null;
208
+ /**
209
+ * The configured hosted-indexer base URL (`config.indexer.baseUrl`), or
210
+ * `null` when reads run over gPA/queryTransport. Earnings hooks prefer it
211
+ * over the per-network hosted default.
212
+ */
213
+ indexerBaseUrl: string | null;
208
214
  /** The configured signer, or `null`. */
209
215
  signer: TransactionSigner | null;
210
216
  /** Validated referrer config, or `null` when none was supplied. */
@@ -1 +0,0 @@
1
- {"version":3,"sources":["../src/strings/index.ts"],"names":[],"mappings":";AAkCO,IAAM,UAAA,GAAa;AAAA;AAAA,EAExB,yBAAA,EACE,sDAAA;AAAA,EACF,6BAAA,EACE,uIAAA;AAAA,EACF,wBAAA,EACE,qFAAA;AAAA;AAAA,EAGF,wBAAA,EACE,iEAAA;AAAA,EACF,wBAAA,EACE,0FAAA;AAAA,EACF,kBAAA,EACE,2CAAA;AAAA,EACF,wBAAA,EACE,8CAAA;AAAA,EACF,gCAAA,EACE,mGAAA;AAAA;AAAA,EAGF,wBAAA,EACE,4HAAA;AAAA;AAAA,EAGF,eAAA,EAAiB,eAAA;AAAA,EACjB,aAAA,EAAe,sBAAA;AAAA,EACf,aAAA,EAAe,uBAAA;AAAA;AAAA,EAGf,UAAA,EAAY,MAAA;AAAA,EACZ,cAAA,EAAgB,kBAAA;AAAA,EAChB,aAAA,EAAe;AACjB;AAwCO,SAAS,CAAA,CACd,EAAA,EACA,IAAA,EACA,OAAA,EACQ;AACR,EAAA,MAAM,OAAA,GAAyB,SAAS,OAAA,IAAW,UAAA;AACnD,EAAA,MAAM,QAAA,GAAW,OAAA,CAAQ,EAAE,CAAA,IAAK,EAAA;AAChC,EAAA,IAAI,IAAA,KAAS,QAAW,OAAO,QAAA;AAC/B,EAAA,OAAO,QAAA,CAAS,OAAA,CAAQ,YAAA,EAAc,CAAC,OAAO,GAAA,KAAgB;AAC5D,IAAA,MAAM,KAAA,GAAQ,KAAK,GAAG,CAAA;AACtB,IAAA,OAAO,KAAA,KAAU,MAAA,GAAY,KAAA,GAAQ,MAAA,CAAO,KAAK,CAAA;AAAA,EACnD,CAAC,CAAA;AACH","file":"chunk-ECU7HGO3.js","sourcesContent":["/**\n * Minimal English string catalog + a `t(id, vars?)` resolver.\n *\n * Every user-facing string in this package and its downstream hooks/components\n * routes through this module so a future `{ locale }` can resolve translations\n * **without an API break** (PLAN_2 Part A design constraint). v1 ships English\n * only; the resolver signature is already locale-shaped.\n *\n * ## Why a catalog and not inline literals\n *\n * Components published to third parties cannot assume the host's language. By\n * keying every literal here:\n * - adding a locale is a data change (a new {@link StringCatalog}), not a code\n * change to every component;\n * - the message ids are a stable contract the components agent binds to;\n * - `{var}` interpolation is centralized and SSR-safe (pure string ops, no\n * `Intl` global assumptions at module scope).\n *\n * @module strings\n */\n\n/**\n * The catalog shape: every message id maps to an English template. `{name}`\n * placeholders are filled by {@link t} from the `vars` argument.\n */\nexport interface StringCatalog {\n readonly [id: string]: string;\n}\n\n/**\n * Default English catalog. Keep ids namespaced by surface\n * (`provider.*`, `referrer.*`, `transport.*`, `hire.*`, ...) so the components\n * agent can extend it without collisions.\n */\nexport const EN_STRINGS = {\n // Provider / context wiring errors (developer-facing, but routed for parity).\n \"provider.missingContext\":\n \"useAgencContext must be used within <AgencProvider>.\",\n \"provider.missingWriteClient\":\n \"No write client is configured. Pass config.client, or config.rpcUrl + config.signer, to <AgencProvider> before using a mutating hook.\",\n \"provider.missingSigner\":\n \"No signer is configured on <AgencProvider>. Connect a wallet or pass config.signer.\",\n\n // Referrer config validation / capability surface.\n \"referrer.invalidWallet\":\n \"Referrer wallet is not a valid base58 Solana address: {wallet}.\",\n \"referrer.invalidFeeBps\":\n \"Referrer feeBps must be an integer between {min} and {max} (basis points); got {feeBps}.\",\n \"referrer.notLive\":\n \"Referral fee is not active for this hire.\",\n \"referrer.notLiveReason\":\n \"No referrer is configured for this provider.\",\n \"referrer.earningsNotLiveReason\":\n \"Referral settlement is live, but aggregated referrer earnings are not yet exposed by the indexer.\",\n\n // Read transport.\n \"transport.noReadSource\":\n \"No read source is configured. Pass an indexer baseUrl, an rpc/queryTransport, to <AgencProvider> or createReadTransport().\",\n\n // Generic loading / empty / error states (components extend these).\n \"state.loading\": \"Loading…\",\n \"state.empty\": \"Nothing to show yet.\",\n \"state.error\": \"Something went wrong.\",\n\n // Hire flow shells (components fill out the rest).\n \"hire.cta\": \"Hire\",\n \"hire.pending\": \"Confirming…\",\n \"hire.funded\": \"Escrow funded.\",\n} as const satisfies StringCatalog;\n\n/** A message id present in the default English catalog. */\nexport type StringId = keyof typeof EN_STRINGS;\n\n/** Interpolation variables for {@link t}: `{name}` → `vars.name`. */\nexport type StringVars = Record<string, string | number | bigint>;\n\n/**\n * Options for {@link t}. `locale` is accepted today (English-only) so adding\n * real locales later does not break the call signature; `catalog` lets a host\n * inject an override/extension catalog.\n */\nexport interface TranslateOptions {\n /** BCP-47 locale tag. v1 resolves everything to English regardless. */\n locale?: string;\n /** Override catalog (e.g. a future locale, or host-supplied copy). */\n catalog?: StringCatalog;\n}\n\n/**\n * Resolve a message id to its localized string with `{var}` interpolation.\n *\n * Unknown ids and unmatched placeholders are returned verbatim (the id itself,\n * or the `{placeholder}` left intact) rather than throwing — a missing string\n * must never crash a money-handling UI.\n *\n * @param id - The message id (a {@link StringId}, or any string for host\n * catalogs).\n * @param vars - Values for `{name}` placeholders in the template.\n * @param options - Optional `locale` (forward-compatible) and `catalog`\n * override.\n * @returns The interpolated string.\n *\n * @example\n * ```ts\n * t(\"referrer.invalidFeeBps\", { min: 0, max: 10000, feeBps: 99999 });\n * // -> \"Referrer feeBps must be an integer between 0 and 10000 ...; got 99999.\"\n * ```\n */\nexport function t(\n id: StringId | (string & {}),\n vars?: StringVars,\n options?: TranslateOptions,\n): string {\n const catalog: StringCatalog = options?.catalog ?? EN_STRINGS;\n const template = catalog[id] ?? id;\n if (vars === undefined) return template;\n return template.replace(/\\{(\\w+)\\}/g, (match, key: string) => {\n const value = vars[key];\n return value === undefined ? match : String(value);\n });\n}\n"]}
@@ -1 +0,0 @@
1
- {"version":3,"sources":["../src/provider/context.ts","../src/hooks/internal.ts","../src/hooks/useHire.ts","../src/hooks/useWalletSigner.ts"],"names":["useCallback"],"mappings":"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","file":"chunk-FAIRTAIB.js","sourcesContent":["/**\n * The React context object + the internal `useAgencContext()` hook.\n *\n * Split from the component file so the context identity is stable and so hooks\n * can import the context without pulling the JSX provider into their module\n * graph. SSR-safe: this module only calls `createContext` at import time, never\n * touches `window`.\n *\n * @module provider/context\n */\nimport { createContext, useContext } from \"react\";\nimport { t } from \"../strings/index.js\";\nimport type { AgencContextValue } from \"../types.js\";\n\n/**\n * The AgenC context. `null` until a `<AgencProvider>` mounts above the consumer\n * — {@link useAgencContext} turns that into a clear developer error.\n */\nexport const AgencContext = createContext<AgencContextValue | null>(null);\nAgencContext.displayName = \"AgencContext\";\n\n/**\n * Read the AgenC context. INTERNAL hook the package's own hooks build on; also\n * exported from the package root so downstream hooks (components agent) can\n * reach the resolved transport/client/referrer.\n *\n * @throws Error when called outside a `<AgencProvider>`.\n */\nexport function useAgencContext(): AgencContextValue {\n const ctx = useContext(AgencContext);\n if (ctx === null) {\n throw new Error(t(\"provider.missingContext\"));\n }\n return ctx;\n}\n","/**\n * Internal helpers shared by the headless hooks.\n *\n * - A namespaced TanStack Query key factory so every hook's cache entries are\n * stable, collision-free, and individually invalidatable.\n * - Tiny guards that turn a missing write client / signer into a clear,\n * catalog-routed error (never a `null.method()` crash) BEFORE a mutation runs.\n *\n * SSR-safe: pure functions, no `window`/`document`, no module-scope side\n * effects.\n *\n * @module hooks/internal\n */\nimport { t } from \"../strings/index.js\";\nimport type {\n Address,\n AgencContextValue,\n MarketplaceClient,\n TransactionSigner,\n} from \"../types.js\";\n\n/** Root namespace for every cache key this package writes. */\nexport const QUERY_KEY_ROOT = \"agenc\" as const;\n\n/**\n * Stable, hierarchical TanStack Query keys. Hooks build their keys ONLY through\n * this factory so a consumer (or a hook) can invalidate a whole sub-tree\n * (`[\"agenc\", \"listings\"]`) or one entity (`[\"agenc\", \"listing\", pda]`).\n *\n * `JSON.stringify` is intentionally NOT used — TanStack compares keys\n * structurally, so passing the raw filter object keeps equality correct for\n * `bigint`/`Address` values without a serialization step.\n */\nexport const queryKeys = {\n /** All listings list queries (with their filter object as the leaf). */\n listings: (filter?: unknown) =>\n [QUERY_KEY_ROOT, \"listings\", filter ?? null] as const,\n /** One listing + its joined provider/track-record/moderation. */\n listing: (pda: string) => [QUERY_KEY_ROOT, \"listing\", pda] as const,\n /** One agent's indexer track record. */\n agentTrackRecord: (agentPda: string) =>\n [QUERY_KEY_ROOT, \"agentTrackRecord\", agentPda] as const,\n /** One task's status (read via transport / svm decode). */\n taskStatus: (taskPda: string) =>\n [QUERY_KEY_ROOT, \"taskStatus\", taskPda] as const,\n /** One task's dispute record. */\n dispute: (taskPda: string) => [QUERY_KEY_ROOT, \"dispute\", taskPda] as const,\n /** One referrer wallet's earnings (indexer-gated; see useReferrerEarnings). */\n referrerEarnings: (wallet: string) =>\n [QUERY_KEY_ROOT, \"referrerEarnings\", wallet] as const,\n} as const;\n\n/**\n * Assert a write client exists, returning it narrowed to non-null. Throws a\n * clear, catalog-routed error when the provider was configured read-only (no\n * `client` and no resolvable `rpcUrl` + `signer`).\n *\n * Mutating hooks call this at the top of their `mutationFn` so the failure is a\n * descriptive Error in the mutation's `error` channel — never a crash.\n *\n * @throws Error (`provider.missingWriteClient`) when `client` is null.\n */\nexport function requireClient(\n client: MarketplaceClient | null,\n): MarketplaceClient {\n if (client === null) {\n throw new Error(t(\"provider.missingWriteClient\"));\n }\n return client;\n}\n\nexport type MutationStatus = \"idle\" | \"pending\" | \"success\" | \"error\";\n\nexport function mutationStatusOf(mutation: {\n isPending: boolean;\n isError: boolean;\n isSuccess: boolean;\n}): MutationStatus {\n if (mutation.isPending) return \"pending\";\n if (mutation.isError) return \"error\";\n if (mutation.isSuccess) return \"success\";\n return \"idle\";\n}\n\n/** Coerce an `Address | string` to its string form for use as a cache key. */\nexport function pdaKey(pda: Address | string): string {\n return String(pda);\n}\n\nexport interface ReferrerArgs {\n referrer?: Address;\n referrerFeeBps?: number;\n}\n\nexport interface ResolvedReferrerArgs {\n referrerArgs: ReferrerArgs;\n referrerInjected: boolean;\n}\n\nexport function resolveReferrerArgs(\n ctx: Pick<AgencContextValue, \"resolveReferrerCapability\">,\n): ResolvedReferrerArgs {\n const capability = ctx.resolveReferrerCapability();\n if (!capability.live || !capability.referrer) {\n return { referrerArgs: {}, referrerInjected: false };\n }\n return {\n referrerArgs: {\n referrer: capability.referrer.wallet,\n referrerFeeBps: capability.referrer.feeBps,\n },\n referrerInjected: true,\n };\n}\n\nexport type SignerOrAddress = TransactionSigner | Address;\n\nexport function signerAddress(signerOrAddress: SignerOrAddress): Address {\n if (typeof signerOrAddress === \"string\") {\n return signerOrAddress;\n }\n if (\n typeof signerOrAddress === \"object\" &&\n signerOrAddress !== null &&\n \"address\" in signerOrAddress &&\n typeof signerOrAddress.address === \"string\"\n ) {\n return signerOrAddress.address;\n }\n throw new Error(\"Expected a TransactionSigner or Address with an address field.\");\n}\n\nexport function withoutReferrerArgs<T extends object>(\n input: T,\n): Omit<T, \"referrer\" | \"referrerFeeBps\"> {\n const {\n referrer: _referrer,\n referrerFeeBps: _referrerFeeBps,\n ...rest\n } = input as T & { referrer?: unknown; referrerFeeBps?: unknown };\n return rest;\n}\n","/**\n * `useHire()` — the hire mutation hook (the embeddable money path).\n *\n * Drives `client.hireFromListing(...)` through the provider's write client and\n * surfaces the resulting transaction signature + minted Task PDA. Typed\n * `AgencError`s from the runtime client are surfaced UNTOUCHED in `error`.\n *\n * ## REFERRER SETTLEMENT\n *\n * The full 84-instruction protocol supports a demand-side referrer leg. This hook:\n * - reads `resolveReferrerCapability()` from context BEFORE building the hire;\n * - when `live === true`, spreads the validated provider referrer into the hire\n * input for both standard and humanless hires;\n * - the `referrerInjected` flag in the result is the audit signal. We never set\n * it true unless the transaction input included the referrer fields.\n *\n * @module hooks/useHire\n */\nimport { useMutation } from \"@tanstack/react-query\";\nimport { useCallback, useMemo } from \"react\";\nimport { findTaskPda } from \"@tetsuo-ai/marketplace-sdk\";\nimport type { facade as facadeNs } from \"@tetsuo-ai/marketplace-sdk\";\nimport { useAgencContext } from \"../provider/context.js\";\nimport type { Address } from \"../types.js\";\nimport {\n requireClient,\n resolveReferrerArgs,\n signerAddress,\n withoutReferrerArgs,\n} from \"./internal.js\";\n\n/**\n * Input to a standard `hire(...)` — a buyer that has a registered marketplace\n * agent (`creatorAgent`). This task settles on the HIRE COMPLETION path (the\n * worker calls `complete_task`). This is the SDK `facade.hireFromListing` input\n * MINUS the fee-payer signers, which default to the provider's write-client\n * signer (authority == creator == buyer). Pass them only to override.\n *\n * NOTE: deliberately NO referrer field — the referrer is provider-level config\n * and is injected only when `resolveReferrerCapability()` is live.\n */\nexport type HireInput = Omit<\n Parameters<typeof facadeNs.hireFromListing>[0],\n \"authority\" | \"creator\" | \"referrer\" | \"referrerFeeBps\"\n> & {\n /** Standard hire (default). */\n humanless?: false;\n /** Override the buyer authority signer (defaults to the client signer). */\n authority?: Parameters<typeof facadeNs.hireFromListing>[0][\"authority\"];\n /** Override the buyer/creator signer (defaults to the client signer). */\n creator?: Parameters<typeof facadeNs.hireFromListing>[0][\"creator\"];\n};\n\n/**\n * Input to a HUMANLESS `hire(...)` — a plain-wallet buyer with NO registered\n * agent (the storefront-visitor path). The task is pinned to CreatorReview, so\n * it settles via the BUYER REVIEW path (`useSubmissionReview` accept/reject) —\n * the human reviews before funds release. This is the SDK\n * `facade.hireFromListingHumanless` input minus the `creator` signer (defaulted\n * to the client signer).\n */\nexport type HumanlessHireInput = Omit<\n Parameters<typeof facadeNs.hireFromListingHumanless>[0],\n \"creator\" | \"referrer\" | \"referrerFeeBps\"\n> & {\n /** Discriminates the humanless storefront-visitor hire. */\n humanless: true;\n /** Override the buyer/creator signer (defaults to the client signer). */\n creator?: Parameters<typeof facadeNs.hireFromListingHumanless>[0][\"creator\"];\n};\n\n/** The union of standard and humanless hire inputs. */\nexport type AnyHireInput = HireInput | HumanlessHireInput;\n\n/** Lifecycle status of the hire mutation. */\nexport type HireStatus = \"idle\" | \"pending\" | \"success\" | \"error\";\n\n/** Result of a settled hire. */\nexport interface HireResult {\n /** The confirmed transaction signature. */\n signature: string;\n /** The minted Task PDA (derived from creator + taskId). */\n taskPda: Address;\n /**\n * Whether a referrer fee leg was injected into THIS hire. Audit signal —\n * never fabricated.\n */\n referrerInjected: boolean;\n}\n\n/** Return value of {@link useHire}. */\nexport interface UseHireResult {\n /** Execute a hire. Resolves to {@link HireResult}; rejects with `AgencError`. */\n hire: (input: AnyHireInput) => Promise<HireResult>;\n /** Current mutation status. */\n status: HireStatus;\n /** The minted Task PDA from the last successful hire, or null. */\n taskPda: Address | null;\n /** The signature from the last successful hire, or null. */\n signature: string | null;\n /** The error from the last hire (typed `AgencError` untouched), or null. */\n error: Error | null;\n /** Whether a hire is currently in flight. */\n isPending: boolean;\n /** Reset the mutation back to idle. */\n reset: () => void;\n}\n\n/**\n * The hire hook.\n *\n * @returns {@link UseHireResult}.\n *\n * @example\n * ```tsx\n * const { hire, status, taskPda, error } = useHire();\n * await hire({\n * listing, creatorAgent, taskId, expectedPrice: price, expectedVersion: 1n,\n * listingSpecHash,\n * });\n * ```\n */\nexport function useHire(): UseHireResult {\n const ctx = useAgencContext();\n\n const mutation = useMutation<HireResult, Error, AnyHireInput>({\n mutationFn: async (input: AnyHireInput): Promise<HireResult> => {\n const client = requireClient(ctx.client);\n\n // Resolve fresh per hire so a provider referrer config change cannot leak\n // stale referral terms into a new transaction.\n const { referrerArgs, referrerInjected } = resolveReferrerArgs(ctx);\n const hireInput = withoutReferrerArgs(input);\n\n const creator = input.creator ?? client.signer;\n let signature: string;\n\n if (input.humanless === true) {\n // Storefront-visitor hire: no creator agent; CreatorReview-pinned, so\n // it settles via the buyer review path (useSubmissionReview).\n const result = await client.hireFromListingHumanless({\n ...hireInput,\n creator,\n ...referrerArgs,\n } as Parameters<typeof facadeNs.hireFromListingHumanless>[0]);\n signature = result.signature;\n } else {\n // Standard hire: authority == creator == buyer (the buyer has an agent).\n const authority = input.authority ?? client.signer;\n const result = await client.hireFromListing({\n ...hireInput,\n authority,\n creator,\n ...referrerArgs,\n } as Parameters<typeof facadeNs.hireFromListing>[0]);\n signature = result.signature;\n }\n\n // Derive the minted Task PDA from (creator, taskId).\n const [taskPda] = await findTaskPda({\n creator: signerAddress(creator),\n taskId: input.taskId,\n });\n\n return { signature, taskPda, referrerInjected };\n },\n });\n\n const hire = useCallback(\n (input: AnyHireInput) => mutation.mutateAsync(input),\n [mutation],\n );\n\n const status: HireStatus = useMemo(() => {\n if (mutation.isPending) return \"pending\";\n if (mutation.isError) return \"error\";\n if (mutation.isSuccess) return \"success\";\n return \"idle\";\n }, [mutation.isPending, mutation.isError, mutation.isSuccess]);\n\n return {\n hire,\n status,\n taskPda: mutation.data?.taskPda ?? null,\n signature: mutation.data?.signature ?? null,\n error: mutation.error ?? null,\n isPending: mutation.isPending,\n reset: mutation.reset,\n };\n}\n","/**\n * `useWalletSigner()` — bridges a browser wallet into the kit `TransactionSigner`\n * the SDK write client expects.\n *\n * ## Adapter seam (the signer-adapters package is not built yet)\n *\n * The dedicated `@tetsuo-ai/signer-adapters` package (the signers agent, PLAN.md\n * P4.1) — which wraps `@solana/react`'s\n * `useWalletAccountTransactionSendingSigner` (Wallet Standard) and the legacy\n * `@solana/wallet-adapter` shim into a kit `TransactionSigner` — does not exist\n * at this hook's build time. So this hook is defined against a **documented\n * adapter interface** ({@link WalletSignerAdapter}) rather than importing that\n * package. A caller passes an adapter (today: a thin wrapper they write, or the\n * signer-adapters hook once it ships) and this hook normalizes it to the\n * `{ signer, connected, connect() }` contract every other hook expects.\n *\n * With NO adapter passed, the hook falls back to the provider's configured\n * `signer` (the `AgencProvider config.signer` slot), so a server-supplied or\n * test signer just works and `connect()` is a no-op.\n *\n * SSR-safe: no `window`/`document`; the adapter (which may touch wallet globals)\n * is the caller's responsibility to gate to the client. This hook only reads\n * what the adapter already resolved.\n *\n * @module hooks/useWalletSigner\n */\nimport { useCallback } from \"react\";\nimport { useAgencContext } from \"../provider/context.js\";\nimport type { TransactionSigner } from \"../types.js\";\n\n/**\n * The minimal adapter shape this hook bridges. The forthcoming\n * `@tetsuo-ai/signer-adapters` hook is expected to return exactly this shape\n * (its `signerFromWalletAccount(...)` resolves the `signer`); until it ships,\n * any object matching this interface works.\n */\nexport interface WalletSignerAdapter {\n /** The resolved kit signer, or null when no wallet is connected. */\n signer: TransactionSigner | null;\n /** Whether a wallet is currently connected. */\n connected?: boolean;\n /** Trigger the wallet connect flow (browser-only). Optional. */\n connect?: () => void | Promise<void>;\n}\n\n/** Options for {@link useWalletSigner}. */\nexport interface UseWalletSignerOptions {\n /**\n * A wallet adapter (e.g. the signer-adapters hook's result). When omitted the\n * hook falls back to the provider's `config.signer`.\n */\n adapter?: WalletSignerAdapter;\n}\n\n/** Return value of {@link useWalletSigner}. */\nexport interface UseWalletSignerResult {\n /** The resolved kit `TransactionSigner`, or null. */\n signer: TransactionSigner | null;\n /** Whether a signer is available (adapter-connected or provider-configured). */\n connected: boolean;\n /** Trigger the wallet connect flow. No-op when no adapter `connect` exists. */\n connect: () => void | Promise<void>;\n}\n\n/**\n * Resolve the active signer for write operations.\n *\n * @param options - Optional wallet adapter; falls back to the provider signer.\n * @returns {@link UseWalletSignerResult}.\n *\n * @example\n * ```tsx\n * // Once @tetsuo-ai/signer-adapters ships:\n * const adapter = useWalletStandardSigner(); // returns WalletSignerAdapter\n * const { signer, connected, connect } = useWalletSigner({ adapter });\n * ```\n */\nexport function useWalletSigner(\n options?: UseWalletSignerOptions,\n): UseWalletSignerResult {\n const ctx = useAgencContext();\n const adapter = options?.adapter;\n\n // Adapter wins when present; otherwise the provider's configured signer.\n const signer: TransactionSigner | null =\n adapter?.signer ?? ctx.signer ?? null;\n const connected =\n adapter !== undefined\n ? (adapter.connected ?? adapter.signer !== null)\n : ctx.signer !== null;\n\n const connect = useCallback(() => {\n // No adapter (or no connect on it) => provider-supplied signer is already\n // \"connected\"; connecting is a no-op rather than an error.\n return adapter?.connect ? adapter.connect() : undefined;\n }, [adapter]);\n\n return { signer, connected, connect };\n}\n"]}