@opensea/sdk 12.2.0 → 12.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/src/api/events.ts CHANGED
@@ -16,6 +16,24 @@ import {
16
16
  /**
17
17
  * Events-related API operations
18
18
  */
19
+ /**
20
+ * Drops `chain` for the one endpoint that ignores it.
21
+ *
22
+ * `GET /api/v2/events` documents no `chain` query parameter and does not filter on one: a request
23
+ * for `chain=solana` still comes back with Ethereum events. Sending it changed nothing, so removing
24
+ * it changes nothing either; it stops the SDK implying a filter the API never applied.
25
+ *
26
+ * Scoped only to this endpoint on purpose. `GET /api/v2/events/accounts/{address}` does document
27
+ * `chain` and does filter, so {@link EventsAPI.getEventsByAccount} passes it through untouched.
28
+ */
29
+ function withoutIgnoredChain(args?: GetEventsArgs): GetEventsArgs | undefined {
30
+ if (!args || args.chain === undefined) {
31
+ return args
32
+ }
33
+ const { chain: _ignored, ...rest } = args
34
+ return rest
35
+ }
36
+
19
37
  export class EventsAPI {
20
38
  constructor(private fetcher: Fetcher) {}
21
39
 
@@ -25,7 +43,7 @@ export class EventsAPI {
25
43
  async getEvents(args?: GetEventsArgs): Promise<GetEventsResponse> {
26
44
  const response = await this.fetcher.get<GetEventsResponse>(
27
45
  getEventsAPIPath(),
28
- args,
46
+ withoutIgnoredChain(args),
29
47
  )
30
48
  return response
31
49
  }
package/src/api/tokens.ts CHANGED
@@ -46,6 +46,28 @@ import type {
46
46
  TokenTimeSeriesArgs,
47
47
  } from "./types"
48
48
 
49
+ /**
50
+ * Forwards a deprecated `next` as `cursor`.
51
+ *
52
+ * These endpoints name the request parameter `cursor` and the response field `next`, so callers
53
+ * who paged by feeding `next` straight back got the first page every time, with no error to notice.
54
+ * `cursor` wins when both are set.
55
+ */
56
+ function withCursor(args?: GetTokensArgs): GetTokensArgs | undefined {
57
+ // Presence, not truthiness: `next: ""` is still the deprecated key, and a falsy check would
58
+ // leave it on the wire as an undocumented parameter, which is the failure this exists to fix.
59
+ if (args === undefined || !("next" in args)) {
60
+ return args
61
+ }
62
+ const { next, ...rest } = args
63
+ // An empty or absent `next` carries no cursor, so it is dropped rather than forwarded as an
64
+ // empty `cursor`, which would put a meaningless parameter on the wire in its place.
65
+ if (rest.cursor !== undefined || !next) {
66
+ return rest
67
+ }
68
+ return { ...rest, cursor: next }
69
+ }
70
+
49
71
  /**
50
72
  * Token-related API operations
51
73
  */
@@ -60,7 +82,7 @@ export class TokensAPI {
60
82
  ): Promise<GetTrendingTokensResponse> {
61
83
  const response = await this.fetcher.get<GetTrendingTokensResponse>(
62
84
  getTrendingTokensPath(),
63
- args,
85
+ withCursor(args),
64
86
  )
65
87
  return response
66
88
  }
@@ -71,7 +93,7 @@ export class TokensAPI {
71
93
  async getTopTokens(args?: GetTokensArgs): Promise<GetTopTokensResponse> {
72
94
  const response = await this.fetcher.get<GetTopTokensResponse>(
73
95
  getTopTokensPath(),
74
- args,
96
+ withCursor(args),
75
97
  )
76
98
  return response
77
99
  }
package/src/api/types.ts CHANGED
@@ -36,6 +36,7 @@ import type {
36
36
  ValidateMetadataResponse as ApiValidateMetadataResponse,
37
37
  WalletVisibilityResponse as ApiWalletVisibilityResponse,
38
38
  AssetMetadataResponse,
39
+ ChainIdentifier,
39
40
  ChainListResponse,
40
41
  ChainResponse,
41
42
  ContractResponse,
@@ -678,8 +679,11 @@ export type AssetEvent =
678
679
  * @category API Query Args
679
680
  */
680
681
  export interface GetEventsArgs {
681
- /** Type of event to filter by */
682
- eventType?: AssetEventType | string
682
+ /**
683
+ * Event types to filter by. The API accepts a repeated parameter, so an array filters on
684
+ * several at once; a single value stays supported.
685
+ */
686
+ eventType?: AssetEventType | string | (AssetEventType | string)[]
683
687
  /** Filter events after this timestamp */
684
688
  after?: number
685
689
  /** Filter events before this timestamp */
@@ -688,7 +692,13 @@ export interface GetEventsArgs {
688
692
  limit?: number
689
693
  /** Cursor for pagination */
690
694
  next?: string
691
- /** Chain to filter by */
695
+ /**
696
+ * Chain to filter by. Honoured by `getEventsByAccount`, whose endpoint documents it.
697
+ *
698
+ * Ignored by `getEvents`: `GET /api/v2/events` documents no `chain` parameter and does not
699
+ * filter on one, so a request for `chain=solana` still returns Ethereum events. The SDK no
700
+ * longer sends it there rather than implying a filter that never applied.
701
+ */
692
702
  chain?: string
693
703
  }
694
704
 
@@ -807,8 +817,22 @@ export type GetTopTokensResponse = Camelize<
807
817
  export interface GetTokensArgs {
808
818
  /** Limit the number of results */
809
819
  limit?: number
810
- /** Cursor for pagination */
820
+ /**
821
+ * Cursor for pagination, taken from the `next` field of the previous response.
822
+ *
823
+ * The request parameter is `cursor` while the response field is `next`, which is why
824
+ * {@link GetTokensArgs.next} looked correct and silently paginated nowhere.
825
+ */
826
+ cursor?: string
827
+ /**
828
+ * @deprecated Use {@link GetTokensArgs.cursor}. These endpoints never read a `next` query
829
+ * parameter, so passing this alone returned the first page every time. It is now forwarded as
830
+ * `cursor` so existing callers start paginating instead of looping, and `cursor` wins if both
831
+ * are set.
832
+ */
811
833
  next?: string
834
+ /** Filter to these chains */
835
+ chains?: ChainIdentifier[]
812
836
  }
813
837
 
814
838
  /**
@@ -1422,6 +1446,8 @@ export interface NFTOwnersArgs {
1422
1446
  export interface PortfolioArgs {
1423
1447
  /** Timeframe for P&L / net-worth history calculation. */
1424
1448
  timeframe?: "HOUR" | "DAY" | "WEEK" | "MONTH"
1449
+ /** Filter to these chains */
1450
+ chains?: ChainIdentifier[]
1425
1451
  }
1426
1452
 
1427
1453
  /**
package/src/types.ts CHANGED
@@ -129,6 +129,45 @@ export interface OpenSeaAPIConfig {
129
129
  apiBaseUrl?: string
130
130
  /** Scoped JWT token for wallet-authenticated endpoints. */
131
131
  authToken?: string
132
+ /**
133
+ * Transport used for every request, defaulting to the global `fetch`.
134
+ *
135
+ * The seam for a cache, a shared rate limiter, retries or request-level instrumentation.
136
+ * Without it the only way to wrap requests is to subclass {@link OpenSeaAPI} and override a
137
+ * public method, which ties the wrapper to that method's signature and cannot carry extra
138
+ * per-request context.
139
+ *
140
+ * It receives the fully built URL and init, including the API key and auth headers, so treat
141
+ * anything it logs or caches as sensitive. It is called for the instance's own requests; the
142
+ * static `OpenSeaAPI.requestInstantApiKey` has no instance to read it from and always uses the
143
+ * global `fetch`.
144
+ *
145
+ * A cache built on this must key on the credentials as well as the URL, and must not cache
146
+ * anything but GET. Two callers with different API keys or auth tokens can see different
147
+ * responses for the same URL, and a POST response is not a cacheable representation of one.
148
+ *
149
+ * @example
150
+ * ```ts
151
+ * // One cache per credential: the simplest way to avoid serving one caller's authenticated
152
+ * // response to another is to never share the cache between them.
153
+ * const cache = new Map<string, Response>()
154
+ *
155
+ * const api = new OpenSeaAPI({
156
+ * apiKey,
157
+ * fetch: async (url, init) => {
158
+ * if ((init?.method ?? "GET").toUpperCase() !== "GET") {
159
+ * return globalThis.fetch(url, init)
160
+ * }
161
+ * const cached = cache.get(String(url))
162
+ * if (cached) return cached.clone()
163
+ * const response = await globalThis.fetch(url, init)
164
+ * if (response.ok) cache.set(String(url), response.clone())
165
+ * return response
166
+ * },
167
+ * })
168
+ * ```
169
+ */
170
+ fetch?: typeof globalThis.fetch
132
171
  }
133
172
 
134
173
  /**