@opensea/sdk 11.8.0 → 12.0.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 (72) hide show
  1. package/README.md +46 -15
  2. package/lib/api/api.d.ts +9 -0
  3. package/lib/api/api.js +15 -2
  4. package/lib/api/api.js.map +1 -1
  5. package/lib/api/collections.d.ts +7 -0
  6. package/lib/api/collections.js +10 -1
  7. package/lib/api/collections.js.map +1 -1
  8. package/lib/api/fetcher.d.ts +5 -2
  9. package/lib/api/types.d.ts +20 -64
  10. package/lib/api/types.js.map +1 -1
  11. package/lib/api/walletAuth.d.ts +95 -8
  12. package/lib/api/walletAuth.js +75 -6
  13. package/lib/api/walletAuth.js.map +1 -1
  14. package/lib/index.d.ts +1 -1
  15. package/lib/orders/attribution.d.ts +18 -0
  16. package/lib/orders/attribution.js +29 -0
  17. package/lib/orders/attribution.js.map +1 -0
  18. package/lib/orders/privateListings.js +8 -0
  19. package/lib/orders/privateListings.js.map +1 -1
  20. package/lib/orders/types.d.ts +16 -28
  21. package/lib/orders/types.js.map +1 -1
  22. package/lib/scopes.d.ts +1 -0
  23. package/lib/scopes.js +1 -0
  24. package/lib/scopes.js.map +1 -1
  25. package/lib/sdk/fulfillment.js +7 -3
  26. package/lib/sdk/fulfillment.js.map +1 -1
  27. package/lib/stream/client.d.ts +80 -0
  28. package/lib/stream/client.js +191 -0
  29. package/lib/stream/client.js.map +1 -0
  30. package/lib/stream/constants.d.ts +3 -0
  31. package/lib/stream/constants.js +8 -0
  32. package/lib/stream/constants.js.map +1 -0
  33. package/lib/stream/helpers.d.ts +1 -0
  34. package/lib/stream/helpers.js +8 -0
  35. package/lib/stream/helpers.js.map +1 -0
  36. package/lib/stream/index.d.ts +17 -0
  37. package/lib/stream/index.js +34 -0
  38. package/lib/stream/index.js.map +1 -0
  39. package/lib/stream/transport/phoenix.d.ts +121 -0
  40. package/lib/stream/transport/phoenix.js +642 -0
  41. package/lib/stream/transport/phoenix.js.map +1 -0
  42. package/lib/stream/transport/types.d.ts +85 -0
  43. package/lib/stream/transport/types.js +24 -0
  44. package/lib/stream/transport/types.js.map +1 -0
  45. package/lib/stream/types.d.ts +238 -0
  46. package/lib/stream/types.js +36 -0
  47. package/lib/stream/types.js.map +1 -0
  48. package/lib/types.d.ts +14 -0
  49. package/lib/utils/units.d.ts +5 -0
  50. package/lib/utils/units.js +48 -9
  51. package/lib/utils/units.js.map +1 -1
  52. package/package.json +10 -9
  53. package/src/api/api.ts +19 -2
  54. package/src/api/collections.ts +14 -1
  55. package/src/api/fetcher.ts +5 -2
  56. package/src/api/types.ts +27 -64
  57. package/src/api/walletAuth.ts +100 -13
  58. package/src/index.ts +1 -1
  59. package/src/orders/attribution.ts +29 -0
  60. package/src/orders/privateListings.ts +15 -0
  61. package/src/orders/types.ts +21 -44
  62. package/src/scopes.ts +1 -0
  63. package/src/sdk/fulfillment.ts +8 -3
  64. package/src/stream/client.ts +299 -0
  65. package/src/stream/constants.ts +5 -0
  66. package/src/stream/helpers.ts +3 -0
  67. package/src/stream/index.ts +18 -0
  68. package/src/stream/transport/phoenix.ts +815 -0
  69. package/src/stream/transport/types.ts +91 -0
  70. package/src/stream/types.ts +289 -0
  71. package/src/types.ts +14 -0
  72. package/src/utils/units.ts +54 -9
package/src/api/types.ts CHANGED
@@ -1,9 +1,12 @@
1
1
  import type {
2
+ AccountResolveResponse,
2
3
  AccountSearchResponse as ApiAccountSearchResponse,
3
4
  AgentProfileRelationshipsResponse as ApiAgentProfileRelationshipsResponse,
4
5
  BuildOfferResponse as ApiBuildOfferResponse,
5
6
  CancelResponse as ApiCancelResponse,
6
7
  CollectionSearchResponse as ApiCollectionSearchResponse,
8
+ DropMintRequest as ApiDropMintRequest,
9
+ DropMintResponse as ApiDropMintResponse,
7
10
  Listing as ApiListing,
8
11
  Nft as ApiNft,
9
12
  NftSearchResponse as ApiNftSearchResponse,
@@ -28,8 +31,10 @@ import type {
28
31
  Trait as ApiTrait,
29
32
  TransactionReceiptRequest as ApiTransactionReceiptRequest,
30
33
  TransactionReceiptResponse as ApiTransactionReceiptResponse,
34
+ ValidateMetadataResponse as ApiValidateMetadataResponse,
31
35
  WalletVisibilityResponse as ApiWalletVisibilityResponse,
32
36
  AssetMetadataResponse,
37
+ ChainListResponse,
33
38
  ChainResponse,
34
39
  ContractResponse,
35
40
  DropDetailedResponse,
@@ -354,11 +359,25 @@ export type SvmTransactionDetailsResponse =
354
359
  export type WalletVisibilityResponse = Camelize<ApiWalletVisibilityResponse>
355
360
 
356
361
  /**
357
- * Public agent profile relationships for an account.
362
+ * Public agent profile relationships for an account. Only relationships both
363
+ * accounts confirmed appear here; a pending proposal is visible to the two
364
+ * parties alone, through `listOwnAgentRelationships`.
365
+ *
366
+ * `agentOwner` is the account confirmed to own this one, and is null when
367
+ * there is none. That is ordinary rather than exceptional: an agent nobody
368
+ * declared is a valid agent account. `agents` holds the accounts this one is
369
+ * the confirmed owner of, newest first.
370
+ *
371
+ * The wire response also carries `agent_owner_profile` and
372
+ * `public_agent_wallets`. Both read the retired wallet-level designation, are
373
+ * permanently null and empty, and are removed by AGE-51, so they are omitted
374
+ * here rather than offered as fields a caller might reasonably read.
358
375
  * @category API Response Types
359
376
  */
360
- export type AgentProfileRelationshipsResponse =
361
- Camelize<ApiAgentProfileRelationshipsResponse>
377
+ export type AgentProfileRelationshipsResponse = Omit<
378
+ Camelize<ApiAgentProfileRelationshipsResponse>,
379
+ "agentOwnerProfile" | "publicAgentWallets"
380
+ >
362
381
 
363
382
  /**
364
383
  * Request body for fetching a transaction receipt.
@@ -971,10 +990,7 @@ export type ChainInfo = Camelize<ChainResponse>
971
990
  * Response from OpenSea API for listing supported chains.
972
991
  * @category API Response Types
973
992
  */
974
- export type GetChainsResponse = {
975
- /** List of supported chains */
976
- chains: ChainInfo[]
977
- }
993
+ export type GetChainsResponse = Camelize<ChainListResponse>
978
994
 
979
995
  /**
980
996
  * Token balance for a wallet address. Sourced from `@opensea/api-types`
@@ -1075,27 +1091,13 @@ export interface GetDropsArgs {
1075
1091
  * Request body for building a drop mint transaction.
1076
1092
  * @category API Request Types
1077
1093
  */
1078
- export type DropMintRequest = {
1079
- /** Wallet address that will receive the minted tokens */
1080
- minter: string
1081
- /** Number of tokens to mint (1-100) */
1082
- quantity: number
1083
- }
1094
+ export type DropMintRequest = Camelize<ApiDropMintRequest>
1084
1095
 
1085
1096
  /**
1086
1097
  * Response from OpenSea API for building a drop mint transaction.
1087
1098
  * @category API Response Types
1088
1099
  */
1089
- export type DropMintResponse = {
1090
- /** Transaction target contract address */
1091
- to: string
1092
- /** Encoded transaction data (hex) */
1093
- data: string
1094
- /** Transaction value in wei (hex) */
1095
- value: string
1096
- /** Chain identifier */
1097
- chain: string
1098
- }
1100
+ export type DropMintResponse = Camelize<ApiDropMintResponse>
1099
1101
 
1100
1102
  /**
1101
1103
  * Query args for Get Trending Collections endpoint.
@@ -1143,52 +1145,13 @@ export type GetCollectionsPaginatedResponse = QueryCursorsV2 & {
1143
1145
  * Response from OpenSea API for resolving an account identifier.
1144
1146
  * @category API Response Types
1145
1147
  */
1146
- export type ResolveAccountResponse = {
1147
- /** The resolved wallet address */
1148
- address: string
1149
- /** OpenSea username, if available */
1150
- username?: string
1151
- /** Primary ENS name, if available */
1152
- ensName?: string
1153
- }
1148
+ export type ResolveAccountResponse = Camelize<AccountResolveResponse>
1154
1149
 
1155
1150
  /**
1156
1151
  * Response from OpenSea API for validating NFT metadata.
1157
1152
  * @category API Response Types
1158
1153
  */
1159
- export type ValidateMetadataResponse = {
1160
- /** The asset being validated */
1161
- assetIdentifier: {
1162
- chain: string
1163
- contractAddress: string
1164
- tokenId: string
1165
- }
1166
- /** The token URI */
1167
- tokenUri?: string
1168
- /** Parsed metadata details */
1169
- metadata?: {
1170
- name?: string
1171
- description?: string
1172
- originalImageUrl?: string
1173
- processedImageUrl?: string
1174
- originalAnimationUrl?: string
1175
- processedAnimationUrl?: string
1176
- externalUrl?: string
1177
- backgroundColor?: string
1178
- attributes: {
1179
- traitType: string
1180
- value: string
1181
- displayType?: string
1182
- }[]
1183
- }
1184
- /** Error encountered during metadata ingestion */
1185
- error?: {
1186
- errorType: string
1187
- message: string
1188
- url?: string
1189
- statusCode?: number
1190
- }
1191
- }
1154
+ export type ValidateMetadataResponse = Camelize<ApiValidateMetadataResponse>
1192
1155
 
1193
1156
  /**
1194
1157
  * Response from OpenSea API for fetching raw NFT metadata.
@@ -424,19 +424,6 @@ export class WalletAuthAPI {
424
424
  )
425
425
  }
426
426
 
427
- markWalletAsAgent(wallet: string) {
428
- return this.fetcher.request<OperationResponse<"mark_wallet_as_agent">>(
429
- "PUT",
430
- `/api/v2/accounts/wallets/${segment(wallet)}/agent`,
431
- )
432
- }
433
-
434
- removeWalletAgentDesignation(wallet: string) {
435
- return this.fetcher.request<
436
- OperationResponse<"remove_wallet_agent_designation">
437
- >("DELETE", `/api/v2/accounts/wallets/${segment(wallet)}/agent`)
438
- }
439
-
440
427
  makeWalletPrivate(wallet: string) {
441
428
  return this.fetcher.request<OperationResponse<"make_wallet_private">>(
442
429
  "PUT",
@@ -450,4 +437,104 @@ export class WalletAuthAPI {
450
437
  `/api/v2/accounts/wallets/${segment(wallet)}/private`,
451
438
  )
452
439
  }
440
+
441
+ // ── Agent accounts ────────────────────────────────────────────────
442
+ //
443
+ // An agent is an account, not a flag on a wallet, and ownership is a
444
+ // relationship between two accounts that both sides confirm. It is a
445
+ // declaration, not an authorization: naming an account as your agent
446
+ // grants it nothing. It is self-reported and OpenSea does not verify it.
447
+ //
448
+ // The five writes below need `write:wallets`. `listOwnAgentRelationships`
449
+ // needs `read:wallets`. A client driving the whole handshake needs both, or
450
+ // the list call fails with "Insufficient permissions".
451
+
452
+ /**
453
+ * Declare the authenticated account an agent. Requires `write:wallets`.
454
+ *
455
+ * Independent of ownership: an agent nobody owns is valid. `changed` is
456
+ * false when the account was already an agent, so a retry is
457
+ * distinguishable from a real change.
458
+ */
459
+ declareAgentAccount() {
460
+ return this.fetcher.request<OperationResponse<"declare_agent_account">>(
461
+ "PUT",
462
+ "/api/v2/accounts/agent",
463
+ )
464
+ }
465
+
466
+ /**
467
+ * Withdraw the authenticated account's agent declaration. Requires
468
+ * `write:wallets`.
469
+ */
470
+ withdrawAgentAccountDeclaration() {
471
+ return this.fetcher.request<
472
+ OperationResponse<"withdraw_agent_account_declaration">
473
+ >("DELETE", "/api/v2/accounts/agent")
474
+ }
475
+
476
+ /**
477
+ * Propose an agent ownership relationship. Requires `write:wallets`.
478
+ *
479
+ * `callerRole` says which side the caller is on: `AGENT` means "I am an
480
+ * agent and the counterparty owns me". The caller's own account is never in
481
+ * the body; it comes from the bearer token.
482
+ *
483
+ * Proposing a relationship that is already awaiting you confirms it, so a
484
+ * client that cannot tell who moved first can just propose.
485
+ */
486
+ proposeAgentRelationship(
487
+ body: WalletAuthRequest<"propose_agent_relationship">,
488
+ ) {
489
+ return this.fetcher.request<
490
+ OperationResponse<"propose_agent_relationship">
491
+ >("POST", "/api/v2/accounts/agent-relationships", body)
492
+ }
493
+
494
+ /**
495
+ * Confirm a relationship proposed to the authenticated account. Requires
496
+ * `write:wallets`. An agent ends up with at most one confirmed owner.
497
+ */
498
+ confirmAgentRelationship(
499
+ body: WalletAuthRequest<"confirm_agent_relationship">,
500
+ ) {
501
+ return this.fetcher.request<
502
+ OperationResponse<"confirm_agent_relationship">
503
+ >("POST", "/api/v2/accounts/agent-relationships/confirm", body)
504
+ }
505
+
506
+ /**
507
+ * Withdraw a proposal or revoke a confirmed relationship. Requires
508
+ * `write:wallets`. Either side may do this at any point, and it deletes the
509
+ * relationship rather than marking it inactive.
510
+ *
511
+ * `removed` is false when no such relationship existed, which covers both a
512
+ * counterparty you never proposed to and someone else's relationship.
513
+ *
514
+ * Sent as query parameters rather than a body on purpose: fetch, OkHttp and
515
+ * urllib all drop DELETE bodies by default, and proxies may strip them.
516
+ */
517
+ revokeAgentRelationship(query: WalletAuthQuery<"revoke_agent_relationship">) {
518
+ const params = new URLSearchParams({
519
+ counterparty_address: query.counterpartyAddress,
520
+ caller_role: query.callerRole,
521
+ })
522
+ return this.fetcher.request<OperationResponse<"revoke_agent_relationship">>(
523
+ "DELETE",
524
+ `/api/v2/accounts/agent-relationships?${params}`,
525
+ )
526
+ }
527
+
528
+ /**
529
+ * List the authenticated account's own relationships. Requires
530
+ * `read:wallets`, not `write:wallets`.
531
+ *
532
+ * Includes proposals still awaiting either side. Pending relationships show
533
+ * up here only; a public profile shows confirmed ones alone.
534
+ */
535
+ listOwnAgentRelationships() {
536
+ return this.fetcher.get<OperationResponse<"list_own_agent_relationships">>(
537
+ "/api/v2/accounts/agent-relationships",
538
+ )
539
+ }
453
540
  }
package/src/index.ts CHANGED
@@ -25,7 +25,7 @@ export * from "./utils"
25
25
  * // Example Setup
26
26
  * ```ts
27
27
  * import { ethers } from 'ethers'
28
- * import { OpenSeaSDK, Chain } from 'opensea-js'
28
+ * import { OpenSeaSDK, Chain } from '@opensea/sdk'
29
29
  * const provider = new ethers.JsonRpcProvider('https://mainnet.infura.io')
30
30
  * const client = new OpenSeaSDK(provider, {
31
31
  * chain: Chain.Mainnet
@@ -0,0 +1,29 @@
1
+ /** A 4-byte hex string, the only shape the attribution suffix takes. */
2
+ const CALLDATA_SUFFIX_PATTERN = /^0x[0-9a-f]{8}$/i
3
+
4
+ /**
5
+ * Append the OpenSea attribution suffix to ABI-encoded calldata.
6
+ *
7
+ * The fulfillment endpoints return `calldata_suffix` alongside the transaction
8
+ * they describe: the first four bytes of `keccak256("api.opensea.io")`, which
9
+ * OpenSea's own fills carry as trailing calldata. Seaport reads its arguments
10
+ * from offsets and ignores trailing bytes, so the suffix attributes the fill
11
+ * without affecting execution.
12
+ *
13
+ * This matters because the SDK does not submit the API's calldata. It re-encodes
14
+ * the call from `input_data` and signs that, which drops anything the API had
15
+ * appended, so the suffix has to be re-attached here or the fill lands
16
+ * unattributed.
17
+ *
18
+ * A missing or malformed suffix is ignored rather than raised. Attribution is
19
+ * optional by design and must never be the reason a fill fails.
20
+ */
21
+ export function appendCalldataSuffix(
22
+ calldata: string,
23
+ suffix: string | undefined,
24
+ ): string {
25
+ if (!suffix || !CALLDATA_SUFFIX_PATTERN.test(suffix)) {
26
+ return calldata
27
+ }
28
+ return calldata + suffix.slice(2)
29
+ }
@@ -62,6 +62,21 @@ export const constructPrivateListingCounterOrder = (
62
62
  ) {
63
63
  throw new Error("Not all currency items were the same for private order")
64
64
  }
65
+ // The counter order below sums every payment item into a single offer item
66
+ // denominated in the first item's token, so two different ERC-20s would be
67
+ // aggregated as if they were one. Seaport then rejects the match because
68
+ // the offer and consideration components disagree on token, surfacing as an
69
+ // onchain revert rather than as this error.
70
+ if (
71
+ !paymentItems.every(
72
+ item =>
73
+ item.token.toLowerCase() === paymentItems[0].token.toLowerCase(),
74
+ )
75
+ ) {
76
+ throw new Error(
77
+ "Not all currency items were the same for private order: payment items must all use the same token",
78
+ )
79
+ }
65
80
  }
66
81
 
67
82
  const { aggregatedStartAmount, aggregatedEndAmount } = paymentItems.reduce(
@@ -1,9 +1,10 @@
1
- import type { BasicOrderParametersStruct } from "@opensea/seaport-js/lib/typechain-types/seaport/contracts/Seaport"
2
1
  import type {
3
- AdvancedOrder,
4
- OrderWithCounter,
5
- } from "@opensea/seaport-js/lib/types"
2
+ FulfillListingResponse as ApiFulfillListingResponse,
3
+ FulfillmentData as ApiFulfillmentData,
4
+ } from "@opensea/api-types"
5
+ import type { OrderWithCounter } from "@opensea/seaport-js/lib/types"
6
6
  import type { OpenSeaAccount, OrderSide } from "../types"
7
+ import type { Camelize } from "../utils/case"
7
8
 
8
9
  // Protocol data
9
10
  type OrderProtocolToProtocolData = {
@@ -68,46 +69,22 @@ export type OrderV2 = {
68
69
  remainingQuantity: number
69
70
  }
70
71
 
71
- export type FulfillmentDataResponse = {
72
- protocol: string
73
- fulfillmentData: FulfillmentData
74
- }
75
-
76
- type FulfillmentData = {
77
- transaction: Transaction
78
- orders: ProtocolData[]
79
- }
80
-
81
- type Transaction = {
82
- function: string
83
- chain: number
84
- to: string
85
- value: string
86
- inputData:
87
- | {
88
- // For fulfillAdvancedOrder
89
- advancedOrder: AdvancedOrder
90
- criteriaResolvers?: unknown[]
91
- fulfillerConduitKey?: string
92
- recipient: string
93
- }
94
- | {
95
- // For fulfillBasicOrder
96
- basicOrderParameters: BasicOrderParametersStruct
97
- }
98
- | {
99
- // For fulfillOrder
100
- order: OrderWithCounter
101
- fulfillerConduitKey?: string
102
- recipient: string
103
- }
104
- | {
105
- // Legacy: for backward compatibility
106
- orders:
107
- | OrderWithCounter[]
108
- | AdvancedOrder[]
109
- | BasicOrderParametersStruct[]
110
- }
72
+ /**
73
+ * Response from the fulfillment data endpoints. Camelized from
74
+ * `@opensea/api-types`, with `orders` narrowed to the seaport-js
75
+ * `ProtocolData` shape the SDK hands back to callers.
76
+ *
77
+ * The generated `transaction` carries `calldataSuffix`, the 4-byte attribution
78
+ * suffix {@link FulfillmentManager.fulfillOrder} appends to the calldata, and
79
+ * `inputData` covers all seven Seaport calls the API can return rather than the
80
+ * four the SDK used to declare.
81
+ */
82
+ export type FulfillmentDataResponse = Camelize<
83
+ Omit<ApiFulfillListingResponse, "fulfillment_data">
84
+ > & {
85
+ fulfillmentData: Camelize<Omit<ApiFulfillmentData, "orders">> & {
86
+ orders: ProtocolData[]
87
+ }
111
88
  }
112
89
 
113
90
  // API query types
package/src/scopes.ts CHANGED
@@ -14,6 +14,7 @@ export const OPENSEA_SCOPES = {
14
14
  READ_FAVORITES: "read:favorites",
15
15
  READ_SOCIAL: "read:social",
16
16
  READ_TOOLS: "read:tools",
17
+ READ_WALLETS: "read:wallets",
17
18
  WRITE_FAVORITES: "write:favorites",
18
19
  WRITE_SOCIAL: "write:social",
19
20
  WRITE_TOOLS: "write:tools",
@@ -3,6 +3,7 @@ import type { OrderComponents } from "@opensea/seaport-js/lib/types"
3
3
  import { CONDUIT_CONTROLLER_ABI, ERC20_ABI } from "../abi/abis"
4
4
  import type { Listing, Offer, Order } from "../api/types"
5
5
  import { CONDUIT_CONTROLLER_ADDRESS } from "../constants"
6
+ import { appendCalldataSuffix } from "../orders/attribution"
6
7
  import {
7
8
  getErc20Payment,
8
9
  getFulfillerConduitKey,
@@ -216,9 +217,9 @@ export class FulfillmentManager {
216
217
  } else if (
217
218
  (functionName === "fulfillBasicOrder" ||
218
219
  rawFunctionName === FULFILL_BASIC_ORDER_ALIAS) &&
219
- "basicOrderParameters" in inputData
220
+ "parameters" in inputData
220
221
  ) {
221
- params = [inputData.basicOrderParameters]
222
+ params = [inputData.parameters]
222
223
  } else if (functionName === "fulfillOrder" && "order" in inputData) {
223
224
  params = [
224
225
  inputData.order,
@@ -243,6 +244,10 @@ export class FulfillmentManager {
243
244
  args: params,
244
245
  })
245
246
 
247
+ // Re-encoding from inputData drops the attribution suffix the API appended
248
+ // to its own calldata, so put it back. See appendCalldataSuffix.
249
+ const data = appendCalldataSuffix(encodedData, transaction.calldataSuffix)
250
+
246
251
  // Send the transaction using the signer from wallet
247
252
  const wallet = this.context.wallet
248
253
  if (!("signer" in wallet)) {
@@ -251,7 +256,7 @@ export class FulfillmentManager {
251
256
  const tx = await wallet.signer.sendTransaction({
252
257
  to: transaction.to,
253
258
  value: BigInt(transaction.value),
254
- data: encodedData,
259
+ data,
255
260
  overrides: overrides as Record<string, unknown>,
256
261
  })
257
262