@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,164 @@
1
+ /**
2
+ * The read-transport abstraction — indexer-first with RPC/gPA fallback.
3
+ *
4
+ * `createReadTransport({ indexer?, rpc?, queryTransport? })` returns one
5
+ * {@link ReadTransport}. When an indexer `baseUrl` is set it routes through the
6
+ * SDK's `createIndexerClient` (the scale path); otherwise it falls back to the
7
+ * SDK's gPA `listActiveListings` / account fetch (the trustless path). The two
8
+ * backends return parity shapes BY SDK DESIGN, so callers never branch on which
9
+ * one is live.
10
+ *
11
+ * `queryTransport` is a full override slot — pass a mock/pre-built transport
12
+ * (tests, SSR fixtures) and it is used verbatim.
13
+ *
14
+ * SSR-safe: no `window`/`document` and no Node built-ins at module scope; the
15
+ * SDK's indexer client is browser-safe (fetch + kit codecs only).
16
+ *
17
+ * @module transport
18
+ */
19
+ import { address, isAddress } from "@solana/kit";
20
+ import {
21
+ createIndexerClient,
22
+ getServiceListingDecoder,
23
+ listActiveListings as gpaListActiveListings,
24
+ type IndexerClient,
25
+ } from "@tetsuo-ai/marketplace-sdk";
26
+ import { t } from "../strings/index.js";
27
+ import type {
28
+ Address,
29
+ CreateReadTransportConfig,
30
+ GpaReadSource,
31
+ IndexerConfig,
32
+ ReadListingResult,
33
+ ReadTransport,
34
+ } from "../types.js";
35
+ import type { CreateIndexerClientOptions } from "@tetsuo-ai/marketplace-sdk";
36
+
37
+ /**
38
+ * Thrown when a gPA-fallback transport is asked for an indexer-only capability
39
+ * (aggregated hires / track record have no trustless gPA equivalent).
40
+ */
41
+ export class ReadTransportUnsupportedError extends Error {
42
+ /** The unsupported operation name. */
43
+ readonly operation: string;
44
+ constructor(operation: string) {
45
+ super(
46
+ `Read operation "${operation}" requires the indexer backend; the gPA ` +
47
+ `fallback has no trustless equivalent. Configure an indexer baseUrl on ` +
48
+ `<AgencProvider> to use it.`,
49
+ );
50
+ this.name = "ReadTransportUnsupportedError";
51
+ this.operation = operation;
52
+ }
53
+ }
54
+
55
+ /** Coerce a string|Address PDA into a kit Address (validates base58). */
56
+ function toAddress(pda: Address | string): Address {
57
+ if (typeof pda !== "string") return pda;
58
+ if (!isAddress(pda)) {
59
+ throw new TypeError(`Not a valid base58 Solana address: ${pda}`);
60
+ }
61
+ return address(pda);
62
+ }
63
+
64
+ /** Build the indexer-backed read transport. */
65
+ function indexerReadTransport(
66
+ config: IndexerConfig,
67
+ indexerClientOptions?: Partial<CreateIndexerClientOptions>,
68
+ ): ReadTransport {
69
+ const client: IndexerClient = createIndexerClient({
70
+ baseUrl: config.baseUrl,
71
+ apiKey: config.apiKey,
72
+ ...(indexerClientOptions ?? {}),
73
+ });
74
+ return {
75
+ kind: "indexer",
76
+ listActiveListings: (options) => client.listActiveListings(options),
77
+ async getListing(pda): Promise<ReadListingResult> {
78
+ const listing = await client.getListing(pda);
79
+ const account = getServiceListingDecoder().decode(
80
+ base64ToBytes(listing.accountData),
81
+ );
82
+ return {
83
+ address: toAddress(listing.pda),
84
+ account,
85
+ indexer: listing,
86
+ };
87
+ },
88
+ listingHires: (pda) => client.listingHires(pda),
89
+ agentTrackRecord: (pda) => client.agentTrackRecord(pda),
90
+ };
91
+ }
92
+
93
+ /** Build the gPA-fallback read transport over a kit RPC / ProgramAccountsTransport. */
94
+ function gpaReadTransport(rpc: GpaReadSource): ReadTransport {
95
+ return {
96
+ kind: "gpa",
97
+ listActiveListings: (options) => gpaListActiveListings(rpc, options),
98
+ async getListing(pda): Promise<ReadListingResult> {
99
+ // No single-account decode helper crosses the transport seam here, so we
100
+ // scope the active-listings query down to the one PDA. (The indexer path
101
+ // is the efficient one; this fallback is the trustless escape hatch.)
102
+ const target = toAddress(pda);
103
+ const all = await gpaListActiveListings(rpc, {});
104
+ const hit = all.find((entry) => entry.address === target);
105
+ if (hit === undefined) {
106
+ throw new Error(
107
+ `Listing ${pda} not found among active listings via the gPA ` +
108
+ `fallback (it may be inactive, or your RPC restricts ` +
109
+ `getProgramAccounts — use an indexer baseUrl for single-listing ` +
110
+ `lookups).`,
111
+ );
112
+ }
113
+ return { address: hit.address, account: hit.account };
114
+ },
115
+ listingHires() {
116
+ return Promise.reject(new ReadTransportUnsupportedError("listingHires"));
117
+ },
118
+ agentTrackRecord() {
119
+ return Promise.reject(
120
+ new ReadTransportUnsupportedError("agentTrackRecord"),
121
+ );
122
+ },
123
+ };
124
+ }
125
+
126
+ /** Browser-safe base64 → bytes (atob in browsers, Buffer in Node). */
127
+ function base64ToBytes(b64: string): Uint8Array {
128
+ if (typeof atob === "function") {
129
+ const binary = atob(b64);
130
+ const bytes = new Uint8Array(binary.length);
131
+ for (let i = 0; i < binary.length; i += 1) {
132
+ bytes[i] = binary.charCodeAt(i);
133
+ }
134
+ return bytes;
135
+ }
136
+ // Node fallback — Buffer is always present there.
137
+ return Uint8Array.from(Buffer.from(b64, "base64"));
138
+ }
139
+
140
+ /**
141
+ * Create the unified read transport.
142
+ *
143
+ * Resolution order:
144
+ * 1. `queryTransport` override (wins — tests/mocks/SSR fixtures);
145
+ * 2. `indexer.baseUrl` present → indexer-first transport;
146
+ * 3. `rpc` present → gPA fallback transport;
147
+ * 4. nothing configured → throws a descriptive error.
148
+ *
149
+ * @param config - See {@link CreateReadTransportConfig}.
150
+ * @returns A {@link ReadTransport}.
151
+ * @throws Error when no read source is configured.
152
+ */
153
+ export function createReadTransport(
154
+ config: CreateReadTransportConfig,
155
+ ): ReadTransport {
156
+ if (config.queryTransport) return config.queryTransport;
157
+ if (config.indexer?.baseUrl) {
158
+ return indexerReadTransport(config.indexer, config.indexerClientOptions);
159
+ }
160
+ if (config.rpc) return gpaReadTransport(config.rpc);
161
+ throw new Error(t("transport.noReadSource"));
162
+ }
163
+
164
+ export type { ReadTransport } from "../types.js";
package/src/types.ts ADDED
@@ -0,0 +1,224 @@
1
+ /**
2
+ * Shared types for `@tetsuo-ai/marketplace-react`.
3
+ *
4
+ * Re-exported from the package root so hooks/components agents (and consumers)
5
+ * bind to one canonical set. SDK types are referenced by import, not copied.
6
+ *
7
+ * @module types
8
+ */
9
+ import type {
10
+ Address,
11
+ Rpc,
12
+ GetProgramAccountsApi,
13
+ TransactionSigner,
14
+ } from "@solana/kit";
15
+ import type {
16
+ CreateIndexerClientOptions,
17
+ DecodedProgramAccount,
18
+ IndexerAgentTrackRecord,
19
+ IndexerHire,
20
+ IndexerListing,
21
+ ListActiveListingsOptions,
22
+ MarketplaceClient,
23
+ ProgramAccountsTransport,
24
+ ServiceListing,
25
+ } from "@tetsuo-ai/marketplace-sdk";
26
+
27
+ /**
28
+ * Indexer connection config for the read transport. Mirrors the SDK's
29
+ * {@link CreateIndexerClientOptions} subset the provider needs (baseUrl is
30
+ * what flips the transport into indexer-first mode).
31
+ */
32
+ export interface IndexerConfig {
33
+ /** Base URL of the hosted indexer/storefront API. Presence = indexer-first. */
34
+ baseUrl: string;
35
+ /** Optional API key (`X-Agenc-Api-Key`). Anonymous reads work without it. */
36
+ apiKey?: string;
37
+ }
38
+
39
+ /**
40
+ * A kit RPC capable of `getProgramAccounts`, or any SDK
41
+ * {@link ProgramAccountsTransport} — the gPA fallback read source.
42
+ */
43
+ export type GpaReadSource =
44
+ | Rpc<GetProgramAccountsApi>
45
+ | ProgramAccountsTransport;
46
+
47
+ /**
48
+ * The unified read interface the provider exposes (indexer-first, gPA
49
+ * fallback). Both backends return parity shapes by SDK design, so a hook never
50
+ * branches on which one is live.
51
+ *
52
+ * - `listActiveListings` returns the SAME `Array<{ address, account }>` shape
53
+ * from both the indexer and the gPA path.
54
+ * - `getListing` returns the indexer's rich `IndexerListing` when available;
55
+ * the gPA fallback synthesizes the same shape from a decoded account.
56
+ * - `listingHires` / `agentTrackRecord` are indexer-native; the gPA fallback
57
+ * throws a descriptive {@link ReadTransportUnsupportedError} (no trustless
58
+ * gPA equivalent exists for an aggregated track record).
59
+ */
60
+ export interface ReadTransport {
61
+ /** Which backend is in use — for diagnostics and conditional UI. */
62
+ readonly kind: "indexer" | "gpa";
63
+ /** List active service listings (parity shape across both backends). */
64
+ listActiveListings(
65
+ options?: ListActiveListingsOptions,
66
+ ): Promise<Array<DecodedProgramAccount<ServiceListing>>>;
67
+ /** Fetch one listing by PDA. */
68
+ getListing(pda: Address | string): Promise<ReadListingResult>;
69
+ /** Hires of a listing (indexer-native; gPA fallback is unsupported). */
70
+ listingHires(pda: Address | string): Promise<IndexerHire[]>;
71
+ /** Agent track record (indexer-native; gPA fallback is unsupported). */
72
+ agentTrackRecord(pda: Address | string): Promise<IndexerAgentTrackRecord>;
73
+ }
74
+
75
+ /**
76
+ * The unified `getListing` result. When the indexer backend is live this is the
77
+ * full {@link IndexerListing}; under the gPA fallback the `decoded` projection
78
+ * is absent and `account` carries the decoded on-chain bytes.
79
+ */
80
+ export interface ReadListingResult {
81
+ /** The listing PDA. */
82
+ address: Address;
83
+ /** The decoded on-chain account (always present). */
84
+ account: ServiceListing;
85
+ /** The indexer's rich projection, when the indexer backend served this. */
86
+ indexer?: IndexerListing;
87
+ }
88
+
89
+ /**
90
+ * Options for `createReadTransport`. Supplying `queryTransport` (a mock or a
91
+ * pre-built transport) overrides everything — this is the public test seam the
92
+ * provider re-exposes via `config.queryTransport`.
93
+ */
94
+ export interface CreateReadTransportConfig {
95
+ /** Indexer connection (presence of `baseUrl` selects the indexer backend). */
96
+ indexer?: IndexerConfig;
97
+ /** gPA fallback read source (kit RPC or a ProgramAccountsTransport). */
98
+ rpc?: GpaReadSource;
99
+ /**
100
+ * Full override: a ready-made {@link ReadTransport} (tests/mocks/SSR
101
+ * fixtures). Wins over `indexer` and `rpc`.
102
+ */
103
+ queryTransport?: ReadTransport;
104
+ /** Override the SDK's indexer client factory options (advanced/tests). */
105
+ indexerClientOptions?: Partial<CreateIndexerClientOptions>;
106
+ }
107
+
108
+ /** Target Solana cluster for the provider's default endpoint resolution. */
109
+ export type AgencNetwork = "localnet" | "devnet" | "mainnet";
110
+
111
+ /**
112
+ * Referrer configuration. Accepted + validated + stored ALWAYS; injected into
113
+ * hires only when {@link ReferrerCapability.live} is true (the P6.2 gate — not
114
+ * today). See {@link resolveReferrerCapability}.
115
+ */
116
+ export interface ReferrerConfig {
117
+ /** Referrer wallet that earns the fee. Must be a valid base58 address. */
118
+ wallet: string;
119
+ /**
120
+ * Referral fee in basis points (1 bps = 0.01%). Validated against
121
+ * `[REFERRER_FEE_BPS_MIN, REFERRER_FEE_BPS_MAX]`.
122
+ */
123
+ feeBps: number;
124
+ }
125
+
126
+ /**
127
+ * A validated, normalized referrer config (the stored form). `wallet` is a
128
+ * branded kit {@link Address} once validation passes.
129
+ */
130
+ export interface ValidatedReferrerConfig {
131
+ /** Validated referrer wallet address. */
132
+ wallet: Address;
133
+ /** Validated referral fee in basis points. */
134
+ feeBps: number;
135
+ }
136
+
137
+ /**
138
+ * The runtime answer to "can a referral fee actually be charged on this
139
+ * cluster?". Returned by `resolveReferrerCapability()`.
140
+ *
141
+ * THE P6.2 GATE: `live` is hardcoded `false` today because the on-chain
142
+ * referrer args + 4th settlement leg (PLAN.md P6.2) are unbuilt. When it ships,
143
+ * this resolver will consult P6.5 `getDeployedSurface` instead. Until then:
144
+ * referrer is never injected, earnings hooks return a documented not-live
145
+ * state, and disclosure UI may still show the pending-support copy.
146
+ */
147
+ export interface ReferrerCapability {
148
+ /** Whether referral settlement is live on the target cluster. */
149
+ live: boolean;
150
+ /** Human-readable reason, always set when `live` is false. */
151
+ reason?: string;
152
+ /** The validated referrer config under this provider, if one was supplied. */
153
+ referrer?: ValidatedReferrerConfig;
154
+ }
155
+
156
+ /**
157
+ * Full `<AgencProvider config={...}>` configuration.
158
+ *
159
+ * The `client` and `queryTransport` slots are PUBLIC API: the SDK's
160
+ * `startLocalMarketplace()` litesvm harness exposes a `{ client }` that plugs
161
+ * straight in for hook e2e, and mock read transports use `queryTransport`.
162
+ */
163
+ export interface AgencProviderConfig {
164
+ /** Target cluster; drives default RPC/indexer endpoint resolution. */
165
+ network?: AgencNetwork;
166
+ /** HTTP RPC endpoint. Overrides the network default. */
167
+ rpcUrl?: string;
168
+ /** WebSocket RPC endpoint (for subscriptions). Overrides the network default. */
169
+ rpcSubscriptionsUrl?: string;
170
+ /** Indexer connection — presence of `indexer.baseUrl` selects indexer-first. */
171
+ indexer?: IndexerConfig;
172
+ /** Referrer config (accepted + validated; injected only when P6.2 is live). */
173
+ referrer?: ReferrerConfig;
174
+ /** Signer for write operations (the kit `TransactionSigner`). */
175
+ signer?: TransactionSigner;
176
+ /**
177
+ * Pre-built write client override slot. When set, it is used verbatim and the
178
+ * provider builds no client from `rpcUrl`/`signer`. This is how
179
+ * `startLocalMarketplace().client` plugs in for hook e2e.
180
+ */
181
+ client?: MarketplaceClient;
182
+ /**
183
+ * Pre-built read transport override slot (tests/mocks/SSR fixtures). Wins over
184
+ * `indexer`/`rpc` resolution.
185
+ */
186
+ queryTransport?: ReadTransport;
187
+ }
188
+
189
+ /**
190
+ * The value exposed via React context by `<AgencProvider>` and read by
191
+ * `useAgencContext()`. Hooks bind to THIS shape.
192
+ */
193
+ export interface AgencContextValue {
194
+ /** Resolved target network. */
195
+ network: AgencNetwork;
196
+ /** The unified read transport (indexer-first, gPA fallback). */
197
+ read: ReadTransport;
198
+ /**
199
+ * The write client, or `null` when neither `client` nor `rpcUrl`+`signer`
200
+ * was supplied. Mutating hooks surface a clear error in that case.
201
+ */
202
+ client: MarketplaceClient | null;
203
+ /** The configured signer, or `null`. */
204
+ signer: TransactionSigner | null;
205
+ /** Validated referrer config, or `null` when none was supplied. */
206
+ referrer: ValidatedReferrerConfig | null;
207
+ /**
208
+ * Resolve whether referral settlement is live on this cluster (the P6.2
209
+ * gate). Today always `{ live: false, ... }`.
210
+ */
211
+ resolveReferrerCapability(): ReferrerCapability;
212
+ }
213
+
214
+ export type {
215
+ Address,
216
+ DecodedProgramAccount,
217
+ IndexerAgentTrackRecord,
218
+ IndexerHire,
219
+ IndexerListing,
220
+ ListActiveListingsOptions,
221
+ MarketplaceClient,
222
+ ServiceListing,
223
+ TransactionSigner,
224
+ };