@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.
Files changed (112) hide show
  1. package/CHANGELOG.md +28 -0
  2. package/LICENSE +21 -0
  3. package/README.md +172 -0
  4. package/dist/chunk-5OTKSRHM.js +128 -0
  5. package/dist/chunk-5OTKSRHM.js.map +1 -0
  6. package/dist/chunk-ABS77JB2.js +94 -0
  7. package/dist/chunk-ABS77JB2.js.map +1 -0
  8. package/dist/chunk-GN5DYVN5.js +35 -0
  9. package/dist/chunk-GN5DYVN5.js.map +1 -0
  10. package/dist/chunk-KJMR6OGC.js +1198 -0
  11. package/dist/chunk-KJMR6OGC.js.map +1 -0
  12. package/dist/chunk-YORZNYZZ.js +107 -0
  13. package/dist/chunk-YORZNYZZ.js.map +1 -0
  14. package/dist/components/agenc-components.css +570 -0
  15. package/dist/components/index.cjs +1335 -0
  16. package/dist/components/index.cjs.map +1 -0
  17. package/dist/components/index.d.cts +5 -0
  18. package/dist/components/index.d.ts +5 -0
  19. package/dist/components/index.js +5 -0
  20. package/dist/components/index.js.map +1 -0
  21. package/dist/hooks/index.cjs +493 -0
  22. package/dist/hooks/index.cjs.map +1 -0
  23. package/dist/hooks/index.d.cts +294 -0
  24. package/dist/hooks/index.d.ts +294 -0
  25. package/dist/hooks/index.js +339 -0
  26. package/dist/hooks/index.js.map +1 -0
  27. package/dist/index-BLrlBVj-.d.cts +1129 -0
  28. package/dist/index-CKTYsNPH.d.ts +1129 -0
  29. package/dist/index.cjs +1690 -0
  30. package/dist/index.cjs.map +1 -0
  31. package/dist/index.d.cts +235 -0
  32. package/dist/index.d.ts +235 -0
  33. package/dist/index.js +127 -0
  34. package/dist/index.js.map +1 -0
  35. package/dist/signers/index.cjs +166 -0
  36. package/dist/signers/index.cjs.map +1 -0
  37. package/dist/signers/index.d.cts +136 -0
  38. package/dist/signers/index.d.ts +136 -0
  39. package/dist/signers/index.js +4 -0
  40. package/dist/signers/index.js.map +1 -0
  41. package/dist/testing/index.cjs +62 -0
  42. package/dist/testing/index.cjs.map +1 -0
  43. package/dist/testing/index.d.cts +71 -0
  44. package/dist/testing/index.d.ts +71 -0
  45. package/dist/testing/index.js +60 -0
  46. package/dist/testing/index.js.map +1 -0
  47. package/dist/theme/agenc-tailwind-preset.cjs +184 -0
  48. package/dist/theme/agenc-tokens.css +132 -0
  49. package/dist/types-jvISR6bc.d.cts +135 -0
  50. package/dist/types-jvISR6bc.d.ts +135 -0
  51. package/dist/useAgentTrackRecord-BLf1nrbu.d.cts +249 -0
  52. package/dist/useAgentTrackRecord-BLf1nrbu.d.ts +249 -0
  53. package/package.json +139 -0
  54. package/src/components/DisputeBanner.stories.tsx +39 -0
  55. package/src/components/DisputeBanner.tsx +110 -0
  56. package/src/components/HireButton.stories.tsx +72 -0
  57. package/src/components/HireButton.tsx +151 -0
  58. package/src/components/HireCheckoutModal.stories.tsx +107 -0
  59. package/src/components/HireCheckoutModal.tsx +284 -0
  60. package/src/components/ListingCard.stories.tsx +55 -0
  61. package/src/components/ListingCard.tsx +148 -0
  62. package/src/components/ListingGrid.stories.tsx +44 -0
  63. package/src/components/ListingGrid.tsx +137 -0
  64. package/src/components/Modal.tsx +121 -0
  65. package/src/components/PoweredByAgenC.tsx +85 -0
  66. package/src/components/ProviderCard.stories.tsx +61 -0
  67. package/src/components/ProviderCard.tsx +154 -0
  68. package/src/components/ReferrerDisclosure.tsx +67 -0
  69. package/src/components/ReviewPanel.stories.tsx +65 -0
  70. package/src/components/ReviewPanel.tsx +141 -0
  71. package/src/components/TaskTimeline.stories.tsx +43 -0
  72. package/src/components/TaskTimeline.tsx +156 -0
  73. package/src/components/__fixtures__/index.tsx +173 -0
  74. package/src/components/agenc-components.css +570 -0
  75. package/src/components/badges.tsx +115 -0
  76. package/src/components/format.ts +150 -0
  77. package/src/components/index.ts +102 -0
  78. package/src/components/primitives.tsx +236 -0
  79. package/src/components/strings.ts +131 -0
  80. package/src/components/useFocusTrap.ts +122 -0
  81. package/src/hooks/index.ts +90 -0
  82. package/src/hooks/internal.ts +70 -0
  83. package/src/hooks/useAgentTrackRecord.ts +166 -0
  84. package/src/hooks/useDispute.ts +130 -0
  85. package/src/hooks/useHire.ts +198 -0
  86. package/src/hooks/useListing.ts +138 -0
  87. package/src/hooks/useListings.ts +133 -0
  88. package/src/hooks/useReferrerEarnings.ts +134 -0
  89. package/src/hooks/useSubmissionReview.ts +179 -0
  90. package/src/hooks/useTaskStatus.ts +192 -0
  91. package/src/hooks/useWalletSigner.ts +99 -0
  92. package/src/index.ts +170 -0
  93. package/src/provider/AgencProvider.tsx +169 -0
  94. package/src/provider/context.ts +35 -0
  95. package/src/provider/index.ts +17 -0
  96. package/src/provider/network.ts +68 -0
  97. package/src/provider/referrer.ts +97 -0
  98. package/src/signers/README.md +130 -0
  99. package/src/signers/embedded-wallet-mock.ts +158 -0
  100. package/src/signers/embedded-wallet.ts +64 -0
  101. package/src/signers/index.ts +48 -0
  102. package/src/signers/strings.ts +39 -0
  103. package/src/signers/types.ts +158 -0
  104. package/src/signers/wallet-account.ts +128 -0
  105. package/src/signers/wallet-adapter.ts +149 -0
  106. package/src/strings/index.ts +119 -0
  107. package/src/testing/index.ts +24 -0
  108. package/src/theme/agenc-tailwind-preset.cjs +184 -0
  109. package/src/theme/agenc-tokens.css +132 -0
  110. package/src/theme/index.ts +94 -0
  111. package/src/transport/index.ts +164 -0
  112. package/src/types.ts +224 -0
@@ -0,0 +1,135 @@
1
+ import { Transaction, SignatureBytes } from '@solana/kit';
2
+
3
+ /**
4
+ * Signer-adapter contracts for `@tetsuo-ai/marketplace-react`.
5
+ *
6
+ * Two browser → kit `TransactionSigner` bridges live in this subtree:
7
+ *
8
+ * - **Wallet Standard** ({@link signerFromWalletAccount}): wraps a connected
9
+ * browser wallet (the `@solana/react` /
10
+ * `useWalletAccountTransactionSendingSigner` Wallet Standard path, or any
11
+ * object exposing the `solana:signTransaction` feature) into the kit
12
+ * {@link TransactionSigner} the SDK's `createMarketplaceClient` consumes.
13
+ * - **Embedded / walletless** ({@link signerFromEmbeddedWallet}): the
14
+ * PLAN_2 D-1 "no wallet, no SOL" path. Defines the vendor-neutral
15
+ * {@link EmbeddedWalletProvider} interface ONE chosen vendor (Privy / Dynamic
16
+ * / Web3Auth — `[HUMAN]`-gated) implements, plus a working local-keypair MOCK
17
+ * so the walletless Done-when is testable against localnet without a vendor.
18
+ *
19
+ * SSR-safe: nothing here touches `window`/`document` at module scope. The
20
+ * adapters are plain factory functions; only `provider.connect()` (a user
21
+ * gesture) is browser-bound, and that is the vendor's concern, not ours.
22
+ *
23
+ * @module signers/types
24
+ */
25
+
26
+ /**
27
+ * A Wallet Standard `solana:signTransaction` feature method, narrowed to the
28
+ * single shape {@link signerFromWalletAccount} needs.
29
+ *
30
+ * This mirrors `@solana/wallet-standard-features`'s `SolanaSignTransactionMethod`
31
+ * structurally so callers can pass either the real feature function or a test
32
+ * double without a hard dependency on that package's exact version.
33
+ *
34
+ * Given one or more `{ transaction }` wire-format inputs, it returns one
35
+ * `{ signedTransaction }` output per input (a fully serialized, signed
36
+ * transaction — wallets may modify it, which is why we diff signatures rather
37
+ * than assume identity).
38
+ */
39
+ type WalletStandardSignTransaction = (...inputs: ReadonlyArray<{
40
+ /** Serialized transaction (wire format) to sign. */
41
+ readonly transaction: Uint8Array;
42
+ /** CAIP-2 chain id (e.g. `"solana:devnet"`); forwarded to the wallet. */
43
+ readonly chain?: string;
44
+ /** Optional Wallet Standard account handle (forwarded verbatim). */
45
+ readonly account?: unknown;
46
+ }>) => Promise<ReadonlyArray<{
47
+ /** Serialized, signed transaction (wire format). */
48
+ readonly signedTransaction: Uint8Array;
49
+ }>>;
50
+ /**
51
+ * The minimal Wallet Standard account shape {@link signerFromWalletAccount}
52
+ * consumes. A real `UiWalletAccount` (from `@solana/react` /
53
+ * `@wallet-standard/ui`) is structurally assignable to this; a test double only
54
+ * needs `address` plus a `solana:signTransaction` feature.
55
+ *
56
+ * The feature may be supplied two ways:
57
+ * - inline under `features["solana:signTransaction"].signTransaction`
58
+ * (the raw Wallet Standard layout), or
59
+ * - via the {@link SignerFromWalletAccountOptions.signTransaction} override.
60
+ */
61
+ interface WalletStandardAccountLike {
62
+ /** Base58 account address (becomes the signer's `address`). */
63
+ readonly address: string;
64
+ /** CAIP-2 chains this account supports (used to pick a default `chain`). */
65
+ readonly chains?: readonly string[];
66
+ /** Raw Wallet Standard feature bag, when resolvable off the account. */
67
+ readonly features?: Readonly<Record<string, {
68
+ readonly signTransaction?: WalletStandardSignTransaction;
69
+ } | unknown>>;
70
+ }
71
+ /** Options for {@link signerFromWalletAccount}. */
72
+ interface SignerFromWalletAccountOptions {
73
+ /**
74
+ * CAIP-2 chain id forwarded to the wallet on each sign (e.g.
75
+ * `"solana:devnet"`, `"solana:mainnet"`). Defaults to the account's first
76
+ * `solana:*` chain, else `"solana:mainnet"`.
77
+ */
78
+ chain?: string;
79
+ /**
80
+ * Explicit `solana:signTransaction` feature method. Overrides any feature
81
+ * resolved off `account.features`. This is the seam tests and non-Wallet-
82
+ * Standard wrappers use, and the recommended way to pass the result of
83
+ * `@solana/react`'s wallet hooks when you hold the feature directly.
84
+ */
85
+ signTransaction?: WalletStandardSignTransaction;
86
+ }
87
+ /**
88
+ * Vendor-neutral embedded-wallet provider — the PLAN_2 D-1 walletless seam.
89
+ *
90
+ * ONE `[HUMAN]`-chosen vendor (Privy / Dynamic / Web3Auth) implements this
91
+ * behind their email/social login + key custody. The marketplace layer only
92
+ * ever sees this interface, so templates/widget toggle the vendor by config
93
+ * (the C2 `payments.embedded` boolean) without an API break.
94
+ *
95
+ * The {@link createMockEmbeddedWallet} local-keypair adapter implements it for
96
+ * tests so the "no wallet, no SOL" Done-when runs against localnet today.
97
+ */
98
+ interface EmbeddedWalletProvider {
99
+ /**
100
+ * Trigger the vendor's login/onboarding (email, social, passkey, …) and
101
+ * return a ready signer. Idempotent: calling it again after a connection
102
+ * resolves the existing wallet rather than provisioning a new one.
103
+ *
104
+ * This is the ONLY browser-bound method (it runs behind a user gesture); the
105
+ * factory that wraps the provider stays SSR-safe.
106
+ */
107
+ connect(): Promise<EmbeddedWalletConnection>;
108
+ /** Whether a wallet is currently connected (for headless gating/SSR). */
109
+ isConnected(): boolean;
110
+ /** The connected wallet, or `null` before {@link connect}. */
111
+ getConnection(): EmbeddedWalletConnection | null;
112
+ /** Tear down the session (sign out). Optional — not all vendors expose it. */
113
+ disconnect?(): Promise<void>;
114
+ }
115
+ /**
116
+ * A live embedded-wallet connection: the funded account address plus the
117
+ * primitive that produces signatures.
118
+ *
119
+ * `signTransactions` is the lowest-honest-common-denominator across vendors:
120
+ * given kit {@link Transaction} objects, return this account's
121
+ * {@link SignatureBytes} for each (a partial-signer contract — the vendor never
122
+ * broadcasts, the SDK client's transport does). {@link signerFromEmbeddedWallet}
123
+ * lifts it into a kit {@link TransactionSigner}.
124
+ */
125
+ interface EmbeddedWalletConnection {
126
+ /** The embedded wallet's base58 address. */
127
+ readonly address: string;
128
+ /**
129
+ * Produce this account's signature over each provided transaction WITHOUT
130
+ * sending it. One {@link SignatureBytes} per input, in order.
131
+ */
132
+ signTransactions(transactions: readonly Transaction[]): Promise<readonly SignatureBytes[]>;
133
+ }
134
+
135
+ export type { EmbeddedWalletConnection as E, SignerFromWalletAccountOptions as S, WalletStandardAccountLike as W, EmbeddedWalletProvider as a, WalletStandardSignTransaction as b };
@@ -0,0 +1,249 @@
1
+ import { facade, Dispute, IndexerAgentTrackRecord } from '@tetsuo-ai/marketplace-sdk';
2
+ import { Address } from '@solana/kit';
3
+
4
+ /**
5
+ * Input to a standard `hire(...)` — a buyer that has a registered marketplace
6
+ * agent (`creatorAgent`). This task settles on the HIRE COMPLETION path (the
7
+ * worker calls `complete_task`). This is the SDK `facade.hireFromListing` input
8
+ * MINUS the fee-payer signers, which default to the provider's write-client
9
+ * signer (authority == creator == buyer). Pass them only to override.
10
+ *
11
+ * NOTE: deliberately NO referrer field — the referrer is provider-level config,
12
+ * gated by P6.2, and is never threaded through a per-call hire input.
13
+ */
14
+ type HireInput = Omit<Parameters<typeof facade.hireFromListing>[0], "authority" | "creator"> & {
15
+ /** Standard hire (default). */
16
+ humanless?: false;
17
+ /** Override the buyer authority signer (defaults to the client signer). */
18
+ authority?: Parameters<typeof facade.hireFromListing>[0]["authority"];
19
+ /** Override the buyer/creator signer (defaults to the client signer). */
20
+ creator?: Parameters<typeof facade.hireFromListing>[0]["creator"];
21
+ };
22
+ /**
23
+ * Input to a HUMANLESS `hire(...)` — a plain-wallet buyer with NO registered
24
+ * agent (the storefront-visitor path). The task is pinned to CreatorReview, so
25
+ * it settles via the BUYER REVIEW path (`useSubmissionReview` accept/reject) —
26
+ * the human reviews before funds release. This is the SDK
27
+ * `facade.hireFromListingHumanless` input minus the `creator` signer (defaulted
28
+ * to the client signer).
29
+ */
30
+ type HumanlessHireInput = Omit<Parameters<typeof facade.hireFromListingHumanless>[0], "creator"> & {
31
+ /** Discriminates the humanless storefront-visitor hire. */
32
+ humanless: true;
33
+ /** Override the buyer/creator signer (defaults to the client signer). */
34
+ creator?: Parameters<typeof facade.hireFromListingHumanless>[0]["creator"];
35
+ };
36
+ /** The union of standard and humanless hire inputs. */
37
+ type AnyHireInput = HireInput | HumanlessHireInput;
38
+ /** Lifecycle status of the hire mutation. */
39
+ type HireStatus = "idle" | "pending" | "success" | "error";
40
+ /** Result of a settled hire. */
41
+ interface HireResult {
42
+ /** The confirmed transaction signature. */
43
+ signature: string;
44
+ /** The minted Task PDA (derived from creator + taskId). */
45
+ taskPda: Address;
46
+ /**
47
+ * Whether a referrer fee leg was injected into THIS hire. Always `false`
48
+ * today (the P6.2 gate). Audit signal — never fabricated.
49
+ */
50
+ referrerInjected: boolean;
51
+ }
52
+ /** Return value of {@link useHire}. */
53
+ interface UseHireResult {
54
+ /** Execute a hire. Resolves to {@link HireResult}; rejects with `AgencError`. */
55
+ hire: (input: AnyHireInput) => Promise<HireResult>;
56
+ /** Current mutation status. */
57
+ status: HireStatus;
58
+ /** The minted Task PDA from the last successful hire, or null. */
59
+ taskPda: Address | null;
60
+ /** The signature from the last successful hire, or null. */
61
+ signature: string | null;
62
+ /** The error from the last hire (typed `AgencError` untouched), or null. */
63
+ error: Error | null;
64
+ /** Whether a hire is currently in flight. */
65
+ isPending: boolean;
66
+ /** Reset the mutation back to idle. */
67
+ reset: () => void;
68
+ }
69
+ /**
70
+ * The hire hook.
71
+ *
72
+ * @returns {@link UseHireResult}.
73
+ *
74
+ * @example
75
+ * ```tsx
76
+ * const { hire, status, taskPda, error } = useHire();
77
+ * await hire({
78
+ * listing, creatorAgent, taskId, expectedPrice: price, expectedVersion: 1n,
79
+ * listingSpecHash,
80
+ * });
81
+ * ```
82
+ */
83
+ declare function useHire(): UseHireResult;
84
+
85
+ /** Per-call input for `accept` (task auto-bound; signer defaults to the client). */
86
+ type AcceptInput = Omit<Parameters<typeof facade.acceptTaskResult>[0], "task" | "creator"> & {
87
+ creator?: Parameters<typeof facade.acceptTaskResult>[0]["creator"];
88
+ };
89
+ /** Per-call input for `reject`. */
90
+ type RejectInput = Omit<Parameters<typeof facade.rejectTaskResult>[0], "task" | "creator"> & {
91
+ creator?: Parameters<typeof facade.rejectTaskResult>[0]["creator"];
92
+ };
93
+ /** Per-call input for `requestChanges`. */
94
+ type RequestChangesInput = Omit<Parameters<typeof facade.requestChanges>[0], "task" | "creator"> & {
95
+ creator?: Parameters<typeof facade.requestChanges>[0]["creator"];
96
+ };
97
+ /** Lifecycle status of a review verb. */
98
+ type ReviewStatus = "idle" | "pending" | "success" | "error";
99
+ /** A single review verb's surface. */
100
+ interface ReviewAction<TInput> {
101
+ /** Run the action. Resolves to the tx signature; rejects with `AgencError`. */
102
+ (input: TInput): Promise<string>;
103
+ }
104
+ /** Return value of {@link useSubmissionReview}. */
105
+ interface UseSubmissionReviewResult {
106
+ /** Accept the result and settle to the worker. */
107
+ accept: ReviewAction<AcceptInput>;
108
+ /** Reject the result (with a rejection hash). */
109
+ reject: ReviewAction<RejectInput>;
110
+ /** Request changes (with a changes hash), returning the task to the worker. */
111
+ requestChanges: ReviewAction<RequestChangesInput>;
112
+ /** Aggregate status: `pending` if any verb is in flight, else last settled. */
113
+ status: ReviewStatus;
114
+ /** The most recent error across the three verbs, or null. */
115
+ error: Error | null;
116
+ /** Signature of the last successful action, or null. */
117
+ signature: string | null;
118
+ /** Reset all three mutations to idle. */
119
+ reset: () => void;
120
+ }
121
+ /**
122
+ * Buyer-side review actions for one task.
123
+ *
124
+ * @param taskPda - The Task PDA under review (bound to every verb).
125
+ * @returns {@link UseSubmissionReviewResult}.
126
+ */
127
+ declare function useSubmissionReview(taskPda: Parameters<typeof facade.acceptTaskResult>[0]["task"]): UseSubmissionReviewResult;
128
+
129
+ /** Reads a Dispute account for a task, returning the decoded value or null. */
130
+ type DisputeReader = (taskPda: Address | string) => Promise<Dispute | null>;
131
+ /**
132
+ * Per-call input for `initiate(...)`. This is the SDK `facade.initiateDispute`
133
+ * input minus the fee-payer `authority` signer (defaulted to the client's
134
+ * signer; pass it to override). `task` is bound at hook construction.
135
+ */
136
+ type InitiateDisputeInput = Omit<Parameters<typeof facade.initiateDispute>[0], "task" | "authority"> & {
137
+ /** Override the initiator authority signer (defaults to the client signer). */
138
+ authority?: Parameters<typeof facade.initiateDispute>[0]["authority"];
139
+ };
140
+ /** Lifecycle status of the initiate mutation. */
141
+ type DisputeStatus = "idle" | "pending" | "success" | "error";
142
+ /** Options for {@link useDispute}. */
143
+ interface UseDisputeOptions {
144
+ /** How to read the Dispute account. Without it the read stays idle. */
145
+ disputeReader?: DisputeReader;
146
+ /** Disable the read query. Default `true` when `taskPda` + reader exist. */
147
+ enabled?: boolean;
148
+ }
149
+ /** Return value of {@link useDispute}. */
150
+ interface UseDisputeResult {
151
+ /** The decoded dispute, or null (none open / not yet read). */
152
+ dispute: Dispute | null;
153
+ /** Open a dispute. Resolves to the tx signature; rejects with `AgencError`. */
154
+ initiate: (input: InitiateDisputeInput) => Promise<string>;
155
+ /** Status of the initiate mutation. */
156
+ status: DisputeStatus;
157
+ /** Signature of the last successful initiate, or null. */
158
+ signature: string | null;
159
+ /** The read OR initiate error, or null. */
160
+ error: Error | null;
161
+ /** True while reading the dispute. */
162
+ isLoading: boolean;
163
+ /** Force a dispute refetch. */
164
+ refetch: () => void;
165
+ /** Reset the initiate mutation. */
166
+ reset: () => void;
167
+ }
168
+ /**
169
+ * Dispute entry + state for one task.
170
+ *
171
+ * @param taskPda - The Task PDA (falsy disables the read).
172
+ * @param options - Reader + enabled.
173
+ * @returns {@link UseDisputeResult}.
174
+ */
175
+ declare function useDispute(taskPda: Address | string | undefined | null, options?: UseDisputeOptions): UseDisputeResult;
176
+
177
+ /** A reconstructed outcome event (v1: derived from the slash history). */
178
+ interface TrackRecordOutcome {
179
+ /** Outcome kind. v1 only reconstructs slashes from the event stream. */
180
+ kind: "slash";
181
+ /** The raw slash event from the indexer record. */
182
+ event: IndexerAgentTrackRecord["slashHistory"][number];
183
+ }
184
+ /** The projected track record {@link useAgentTrackRecord} returns. */
185
+ interface AgentTrackRecord {
186
+ /** The agent PDA. */
187
+ agent: Address | string;
188
+ /** Completed-task count (real today). */
189
+ completions: number;
190
+ /** Disputes the agent initiated (real today). */
191
+ disputesInitiated: number;
192
+ /** Disputes the agent lost (real today). */
193
+ disputesLost: number;
194
+ /**
195
+ * Completion rate in `[0,1]`, or `null` when no denominator is inferable.
196
+ * PROVISIONAL until P6.6 supplies the true total-tasks denominator.
197
+ */
198
+ completionRate: number | null;
199
+ /**
200
+ * Dispute rate in `[0,1]`, or `null` when no denominator is inferable.
201
+ * PROVISIONAL until P6.6.
202
+ */
203
+ disputeRate: number | null;
204
+ /** Reconstructed slash history (real today). */
205
+ slashHistory: IndexerAgentTrackRecord["slashHistory"];
206
+ /** Reconstructed recent outcomes (v1: from slash history). */
207
+ recentOutcomes: TrackRecordOutcome[];
208
+ /** True while any rate is provisional/derived (P6.6 audit signal). */
209
+ partial: boolean;
210
+ }
211
+ /** Options for {@link useAgentTrackRecord}. */
212
+ interface UseAgentTrackRecordOptions {
213
+ /** Disable the query. Default `true` when `agentPda` is set. */
214
+ enabled?: boolean;
215
+ }
216
+ /** Return value of {@link useAgentTrackRecord}. */
217
+ interface UseAgentTrackRecordResult {
218
+ /** The projected track record, or null until loaded. */
219
+ trackRecord: AgentTrackRecord | null;
220
+ /** Convenience: `trackRecord?.completionRate ?? null`. */
221
+ completionRate: number | null;
222
+ /** Convenience: `trackRecord?.disputeRate ?? null`. */
223
+ disputeRate: number | null;
224
+ /** Convenience: `trackRecord?.slashHistory ?? []`. */
225
+ slashHistory: IndexerAgentTrackRecord["slashHistory"];
226
+ /** Convenience: `trackRecord?.recentOutcomes ?? []`. */
227
+ recentOutcomes: TrackRecordOutcome[];
228
+ /** True while loading. */
229
+ isLoading: boolean;
230
+ /** The error (e.g. `ReadTransportUnsupportedError` under gPA), or null. */
231
+ error: Error | null;
232
+ /** Force a refetch. */
233
+ refetch: () => void;
234
+ }
235
+ /**
236
+ * Project the raw indexer record into the partial track-record contract. Kept
237
+ * exported + pure so structural tests can assert the projection directly.
238
+ */
239
+ declare function projectTrackRecord(raw: IndexerAgentTrackRecord): AgentTrackRecord;
240
+ /**
241
+ * Read an agent's (partial) track record.
242
+ *
243
+ * @param agentPda - The AgentRegistration PDA (falsy disables the hook).
244
+ * @param options - `enabled` override.
245
+ * @returns {@link UseAgentTrackRecordResult}.
246
+ */
247
+ declare function useAgentTrackRecord(agentPda: Address | string | undefined | null, options?: UseAgentTrackRecordOptions): UseAgentTrackRecordResult;
248
+
249
+ export { type AcceptInput as A, type DisputeReader as D, type HireInput as H, type InitiateDisputeInput as I, type RejectInput as R, type TrackRecordOutcome as T, type UseAgentTrackRecordOptions as U, type AgentTrackRecord as a, type AnyHireInput as b, type DisputeStatus as c, type HireResult as d, type HireStatus as e, type HumanlessHireInput as f, type RequestChangesInput as g, type ReviewAction as h, type ReviewStatus as i, type UseAgentTrackRecordResult as j, type UseDisputeOptions as k, type UseDisputeResult as l, type UseHireResult as m, type UseSubmissionReviewResult as n, useDispute as o, projectTrackRecord as p, useHire as q, useSubmissionReview as r, useAgentTrackRecord as u };
@@ -0,0 +1,249 @@
1
+ import { facade, Dispute, IndexerAgentTrackRecord } from '@tetsuo-ai/marketplace-sdk';
2
+ import { Address } from '@solana/kit';
3
+
4
+ /**
5
+ * Input to a standard `hire(...)` — a buyer that has a registered marketplace
6
+ * agent (`creatorAgent`). This task settles on the HIRE COMPLETION path (the
7
+ * worker calls `complete_task`). This is the SDK `facade.hireFromListing` input
8
+ * MINUS the fee-payer signers, which default to the provider's write-client
9
+ * signer (authority == creator == buyer). Pass them only to override.
10
+ *
11
+ * NOTE: deliberately NO referrer field — the referrer is provider-level config,
12
+ * gated by P6.2, and is never threaded through a per-call hire input.
13
+ */
14
+ type HireInput = Omit<Parameters<typeof facade.hireFromListing>[0], "authority" | "creator"> & {
15
+ /** Standard hire (default). */
16
+ humanless?: false;
17
+ /** Override the buyer authority signer (defaults to the client signer). */
18
+ authority?: Parameters<typeof facade.hireFromListing>[0]["authority"];
19
+ /** Override the buyer/creator signer (defaults to the client signer). */
20
+ creator?: Parameters<typeof facade.hireFromListing>[0]["creator"];
21
+ };
22
+ /**
23
+ * Input to a HUMANLESS `hire(...)` — a plain-wallet buyer with NO registered
24
+ * agent (the storefront-visitor path). The task is pinned to CreatorReview, so
25
+ * it settles via the BUYER REVIEW path (`useSubmissionReview` accept/reject) —
26
+ * the human reviews before funds release. This is the SDK
27
+ * `facade.hireFromListingHumanless` input minus the `creator` signer (defaulted
28
+ * to the client signer).
29
+ */
30
+ type HumanlessHireInput = Omit<Parameters<typeof facade.hireFromListingHumanless>[0], "creator"> & {
31
+ /** Discriminates the humanless storefront-visitor hire. */
32
+ humanless: true;
33
+ /** Override the buyer/creator signer (defaults to the client signer). */
34
+ creator?: Parameters<typeof facade.hireFromListingHumanless>[0]["creator"];
35
+ };
36
+ /** The union of standard and humanless hire inputs. */
37
+ type AnyHireInput = HireInput | HumanlessHireInput;
38
+ /** Lifecycle status of the hire mutation. */
39
+ type HireStatus = "idle" | "pending" | "success" | "error";
40
+ /** Result of a settled hire. */
41
+ interface HireResult {
42
+ /** The confirmed transaction signature. */
43
+ signature: string;
44
+ /** The minted Task PDA (derived from creator + taskId). */
45
+ taskPda: Address;
46
+ /**
47
+ * Whether a referrer fee leg was injected into THIS hire. Always `false`
48
+ * today (the P6.2 gate). Audit signal — never fabricated.
49
+ */
50
+ referrerInjected: boolean;
51
+ }
52
+ /** Return value of {@link useHire}. */
53
+ interface UseHireResult {
54
+ /** Execute a hire. Resolves to {@link HireResult}; rejects with `AgencError`. */
55
+ hire: (input: AnyHireInput) => Promise<HireResult>;
56
+ /** Current mutation status. */
57
+ status: HireStatus;
58
+ /** The minted Task PDA from the last successful hire, or null. */
59
+ taskPda: Address | null;
60
+ /** The signature from the last successful hire, or null. */
61
+ signature: string | null;
62
+ /** The error from the last hire (typed `AgencError` untouched), or null. */
63
+ error: Error | null;
64
+ /** Whether a hire is currently in flight. */
65
+ isPending: boolean;
66
+ /** Reset the mutation back to idle. */
67
+ reset: () => void;
68
+ }
69
+ /**
70
+ * The hire hook.
71
+ *
72
+ * @returns {@link UseHireResult}.
73
+ *
74
+ * @example
75
+ * ```tsx
76
+ * const { hire, status, taskPda, error } = useHire();
77
+ * await hire({
78
+ * listing, creatorAgent, taskId, expectedPrice: price, expectedVersion: 1n,
79
+ * listingSpecHash,
80
+ * });
81
+ * ```
82
+ */
83
+ declare function useHire(): UseHireResult;
84
+
85
+ /** Per-call input for `accept` (task auto-bound; signer defaults to the client). */
86
+ type AcceptInput = Omit<Parameters<typeof facade.acceptTaskResult>[0], "task" | "creator"> & {
87
+ creator?: Parameters<typeof facade.acceptTaskResult>[0]["creator"];
88
+ };
89
+ /** Per-call input for `reject`. */
90
+ type RejectInput = Omit<Parameters<typeof facade.rejectTaskResult>[0], "task" | "creator"> & {
91
+ creator?: Parameters<typeof facade.rejectTaskResult>[0]["creator"];
92
+ };
93
+ /** Per-call input for `requestChanges`. */
94
+ type RequestChangesInput = Omit<Parameters<typeof facade.requestChanges>[0], "task" | "creator"> & {
95
+ creator?: Parameters<typeof facade.requestChanges>[0]["creator"];
96
+ };
97
+ /** Lifecycle status of a review verb. */
98
+ type ReviewStatus = "idle" | "pending" | "success" | "error";
99
+ /** A single review verb's surface. */
100
+ interface ReviewAction<TInput> {
101
+ /** Run the action. Resolves to the tx signature; rejects with `AgencError`. */
102
+ (input: TInput): Promise<string>;
103
+ }
104
+ /** Return value of {@link useSubmissionReview}. */
105
+ interface UseSubmissionReviewResult {
106
+ /** Accept the result and settle to the worker. */
107
+ accept: ReviewAction<AcceptInput>;
108
+ /** Reject the result (with a rejection hash). */
109
+ reject: ReviewAction<RejectInput>;
110
+ /** Request changes (with a changes hash), returning the task to the worker. */
111
+ requestChanges: ReviewAction<RequestChangesInput>;
112
+ /** Aggregate status: `pending` if any verb is in flight, else last settled. */
113
+ status: ReviewStatus;
114
+ /** The most recent error across the three verbs, or null. */
115
+ error: Error | null;
116
+ /** Signature of the last successful action, or null. */
117
+ signature: string | null;
118
+ /** Reset all three mutations to idle. */
119
+ reset: () => void;
120
+ }
121
+ /**
122
+ * Buyer-side review actions for one task.
123
+ *
124
+ * @param taskPda - The Task PDA under review (bound to every verb).
125
+ * @returns {@link UseSubmissionReviewResult}.
126
+ */
127
+ declare function useSubmissionReview(taskPda: Parameters<typeof facade.acceptTaskResult>[0]["task"]): UseSubmissionReviewResult;
128
+
129
+ /** Reads a Dispute account for a task, returning the decoded value or null. */
130
+ type DisputeReader = (taskPda: Address | string) => Promise<Dispute | null>;
131
+ /**
132
+ * Per-call input for `initiate(...)`. This is the SDK `facade.initiateDispute`
133
+ * input minus the fee-payer `authority` signer (defaulted to the client's
134
+ * signer; pass it to override). `task` is bound at hook construction.
135
+ */
136
+ type InitiateDisputeInput = Omit<Parameters<typeof facade.initiateDispute>[0], "task" | "authority"> & {
137
+ /** Override the initiator authority signer (defaults to the client signer). */
138
+ authority?: Parameters<typeof facade.initiateDispute>[0]["authority"];
139
+ };
140
+ /** Lifecycle status of the initiate mutation. */
141
+ type DisputeStatus = "idle" | "pending" | "success" | "error";
142
+ /** Options for {@link useDispute}. */
143
+ interface UseDisputeOptions {
144
+ /** How to read the Dispute account. Without it the read stays idle. */
145
+ disputeReader?: DisputeReader;
146
+ /** Disable the read query. Default `true` when `taskPda` + reader exist. */
147
+ enabled?: boolean;
148
+ }
149
+ /** Return value of {@link useDispute}. */
150
+ interface UseDisputeResult {
151
+ /** The decoded dispute, or null (none open / not yet read). */
152
+ dispute: Dispute | null;
153
+ /** Open a dispute. Resolves to the tx signature; rejects with `AgencError`. */
154
+ initiate: (input: InitiateDisputeInput) => Promise<string>;
155
+ /** Status of the initiate mutation. */
156
+ status: DisputeStatus;
157
+ /** Signature of the last successful initiate, or null. */
158
+ signature: string | null;
159
+ /** The read OR initiate error, or null. */
160
+ error: Error | null;
161
+ /** True while reading the dispute. */
162
+ isLoading: boolean;
163
+ /** Force a dispute refetch. */
164
+ refetch: () => void;
165
+ /** Reset the initiate mutation. */
166
+ reset: () => void;
167
+ }
168
+ /**
169
+ * Dispute entry + state for one task.
170
+ *
171
+ * @param taskPda - The Task PDA (falsy disables the read).
172
+ * @param options - Reader + enabled.
173
+ * @returns {@link UseDisputeResult}.
174
+ */
175
+ declare function useDispute(taskPda: Address | string | undefined | null, options?: UseDisputeOptions): UseDisputeResult;
176
+
177
+ /** A reconstructed outcome event (v1: derived from the slash history). */
178
+ interface TrackRecordOutcome {
179
+ /** Outcome kind. v1 only reconstructs slashes from the event stream. */
180
+ kind: "slash";
181
+ /** The raw slash event from the indexer record. */
182
+ event: IndexerAgentTrackRecord["slashHistory"][number];
183
+ }
184
+ /** The projected track record {@link useAgentTrackRecord} returns. */
185
+ interface AgentTrackRecord {
186
+ /** The agent PDA. */
187
+ agent: Address | string;
188
+ /** Completed-task count (real today). */
189
+ completions: number;
190
+ /** Disputes the agent initiated (real today). */
191
+ disputesInitiated: number;
192
+ /** Disputes the agent lost (real today). */
193
+ disputesLost: number;
194
+ /**
195
+ * Completion rate in `[0,1]`, or `null` when no denominator is inferable.
196
+ * PROVISIONAL until P6.6 supplies the true total-tasks denominator.
197
+ */
198
+ completionRate: number | null;
199
+ /**
200
+ * Dispute rate in `[0,1]`, or `null` when no denominator is inferable.
201
+ * PROVISIONAL until P6.6.
202
+ */
203
+ disputeRate: number | null;
204
+ /** Reconstructed slash history (real today). */
205
+ slashHistory: IndexerAgentTrackRecord["slashHistory"];
206
+ /** Reconstructed recent outcomes (v1: from slash history). */
207
+ recentOutcomes: TrackRecordOutcome[];
208
+ /** True while any rate is provisional/derived (P6.6 audit signal). */
209
+ partial: boolean;
210
+ }
211
+ /** Options for {@link useAgentTrackRecord}. */
212
+ interface UseAgentTrackRecordOptions {
213
+ /** Disable the query. Default `true` when `agentPda` is set. */
214
+ enabled?: boolean;
215
+ }
216
+ /** Return value of {@link useAgentTrackRecord}. */
217
+ interface UseAgentTrackRecordResult {
218
+ /** The projected track record, or null until loaded. */
219
+ trackRecord: AgentTrackRecord | null;
220
+ /** Convenience: `trackRecord?.completionRate ?? null`. */
221
+ completionRate: number | null;
222
+ /** Convenience: `trackRecord?.disputeRate ?? null`. */
223
+ disputeRate: number | null;
224
+ /** Convenience: `trackRecord?.slashHistory ?? []`. */
225
+ slashHistory: IndexerAgentTrackRecord["slashHistory"];
226
+ /** Convenience: `trackRecord?.recentOutcomes ?? []`. */
227
+ recentOutcomes: TrackRecordOutcome[];
228
+ /** True while loading. */
229
+ isLoading: boolean;
230
+ /** The error (e.g. `ReadTransportUnsupportedError` under gPA), or null. */
231
+ error: Error | null;
232
+ /** Force a refetch. */
233
+ refetch: () => void;
234
+ }
235
+ /**
236
+ * Project the raw indexer record into the partial track-record contract. Kept
237
+ * exported + pure so structural tests can assert the projection directly.
238
+ */
239
+ declare function projectTrackRecord(raw: IndexerAgentTrackRecord): AgentTrackRecord;
240
+ /**
241
+ * Read an agent's (partial) track record.
242
+ *
243
+ * @param agentPda - The AgentRegistration PDA (falsy disables the hook).
244
+ * @param options - `enabled` override.
245
+ * @returns {@link UseAgentTrackRecordResult}.
246
+ */
247
+ declare function useAgentTrackRecord(agentPda: Address | string | undefined | null, options?: UseAgentTrackRecordOptions): UseAgentTrackRecordResult;
248
+
249
+ export { type AcceptInput as A, type DisputeReader as D, type HireInput as H, type InitiateDisputeInput as I, type RejectInput as R, type TrackRecordOutcome as T, type UseAgentTrackRecordOptions as U, type AgentTrackRecord as a, type AnyHireInput as b, type DisputeStatus as c, type HireResult as d, type HireStatus as e, type HumanlessHireInput as f, type RequestChangesInput as g, type ReviewAction as h, type ReviewStatus as i, type UseAgentTrackRecordResult as j, type UseDisputeOptions as k, type UseDisputeResult as l, type UseHireResult as m, type UseSubmissionReviewResult as n, useDispute as o, projectTrackRecord as p, useHire as q, useSubmissionReview as r, useAgentTrackRecord as u };