@opensea/sdk 11.1.1 → 11.2.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 (61) hide show
  1. package/lib/api/accounts.d.ts +13 -1
  2. package/lib/api/accounts.js +18 -0
  3. package/lib/api/accounts.js.map +1 -1
  4. package/lib/api/api.d.ts +14 -1
  5. package/lib/api/api.js +22 -0
  6. package/lib/api/api.js.map +1 -1
  7. package/lib/api/apiPaths.d.ts +3 -0
  8. package/lib/api/apiPaths.js +13 -1
  9. package/lib/api/apiPaths.js.map +1 -1
  10. package/lib/api/types.d.ts +31 -1
  11. package/lib/auth/index.d.ts +65 -0
  12. package/lib/auth/index.js +168 -0
  13. package/lib/auth/index.js.map +1 -0
  14. package/lib/auth/oauth-types.d.ts +69 -0
  15. package/lib/auth/oauth-types.js +3 -0
  16. package/lib/auth/oauth-types.js.map +1 -0
  17. package/lib/auth/oauth.d.ts +109 -0
  18. package/lib/auth/oauth.js +342 -0
  19. package/lib/auth/oauth.js.map +1 -0
  20. package/lib/auth/types.d.ts +50 -0
  21. package/lib/auth/types.js +3 -0
  22. package/lib/auth/types.js.map +1 -0
  23. package/lib/index.d.ts +7 -1
  24. package/lib/index.js +9 -1
  25. package/lib/index.js.map +1 -1
  26. package/lib/scopes.d.ts +29 -0
  27. package/lib/scopes.js +27 -0
  28. package/lib/scopes.js.map +1 -0
  29. package/lib/sdk/base.d.ts +1 -0
  30. package/lib/sdk/base.js +6 -3
  31. package/lib/sdk/base.js.map +1 -1
  32. package/lib/sdk/cancellation.js +33 -23
  33. package/lib/sdk/cancellation.js.map +1 -1
  34. package/lib/types.d.ts +5 -1
  35. package/lib/types.js +1 -0
  36. package/lib/types.js.map +1 -1
  37. package/lib/utils/chain.d.ts +1 -1
  38. package/lib/utils/chain.js +29 -5
  39. package/lib/utils/chain.js.map +1 -1
  40. package/lib/utils/chainIds.generated.js +1 -0
  41. package/lib/utils/chainIds.generated.js.map +1 -1
  42. package/lib/viem.d.ts +1 -0
  43. package/lib/viem.js +1 -0
  44. package/lib/viem.js.map +1 -1
  45. package/package.json +2 -2
  46. package/src/api/accounts.ts +41 -0
  47. package/src/api/api.ts +36 -0
  48. package/src/api/apiPaths.ts +12 -0
  49. package/src/api/types.ts +36 -0
  50. package/src/auth/index.ts +230 -0
  51. package/src/auth/oauth-types.ts +73 -0
  52. package/src/auth/oauth.ts +428 -0
  53. package/src/auth/types.ts +55 -0
  54. package/src/index.ts +10 -0
  55. package/src/scopes.ts +39 -0
  56. package/src/sdk/base.ts +6 -4
  57. package/src/sdk/cancellation.ts +39 -25
  58. package/src/types.ts +4 -0
  59. package/src/utils/chain.ts +36 -5
  60. package/src/utils/chainIds.generated.ts +1 -0
  61. package/src/viem.ts +1 -0
@@ -0,0 +1,230 @@
1
+ import type {
2
+ AuthenticateOptions,
3
+ AuthNonceResponse,
4
+ AuthSigner,
5
+ AuthToken,
6
+ AuthTokenResponse,
7
+ OpenSeaAuthConfig,
8
+ } from "./types"
9
+
10
+ export type {
11
+ AuthenticateOptions,
12
+ AuthNonceResponse,
13
+ AuthSigner,
14
+ AuthToken,
15
+ AuthTokenResponse,
16
+ OpenSeaAuthConfig,
17
+ }
18
+
19
+ const DEFAULT_AUTH_BASE_URL = "https://auth.opensea.io"
20
+
21
+ /** Buffer (in ms) before expiry at which auto-refresh triggers. */
22
+ const REFRESH_BUFFER_MS = 60_000
23
+
24
+ /**
25
+ * SIWE-based authentication helper for OpenSea.
26
+ *
27
+ * Handles the full sign-in flow: nonce request, EIP-4361 message generation,
28
+ * signature exchange, token caching, and automatic refresh.
29
+ *
30
+ * @example
31
+ * ```ts
32
+ * import { OpenSeaAuth } from "@opensea/sdk"
33
+ *
34
+ * const auth = new OpenSeaAuth()
35
+ * const token = await auth.authenticate(signer, {
36
+ * scopes: ["read:eligibility", "write:orders"],
37
+ * })
38
+ *
39
+ * // Auto-refresh before expiry
40
+ * const freshToken = await auth.getValidToken()
41
+ *
42
+ * // Revoke
43
+ * await auth.revoke(token.accessToken)
44
+ * ```
45
+ *
46
+ * @category Authentication
47
+ */
48
+ export class OpenSeaAuth {
49
+ private readonly authBaseUrl: string
50
+ private cachedToken: AuthToken | undefined
51
+
52
+ constructor(config: OpenSeaAuthConfig = {}) {
53
+ this.authBaseUrl = (config.authBaseUrl ?? DEFAULT_AUTH_BASE_URL).replace(
54
+ /\/$/,
55
+ "",
56
+ )
57
+ }
58
+
59
+ /**
60
+ * Run the full SIWE authentication flow:
61
+ * 1. Request a nonce from the auth server
62
+ * 2. Build an EIP-4361 SIWE message
63
+ * 3. Sign it with the provided signer
64
+ * 4. Exchange the signature for a scoped JWT token
65
+ *
66
+ * The returned token is cached in memory and will be auto-refreshed
67
+ * by {@link getValidToken}.
68
+ */
69
+ async authenticate(
70
+ signer: AuthSigner,
71
+ options: AuthenticateOptions = {},
72
+ ): Promise<AuthToken> {
73
+ const address = await signer.getAddress()
74
+ const { nonce } = await this.requestNonce()
75
+ const message = generateSiweMessage(
76
+ address,
77
+ options.scopes ?? [],
78
+ nonce,
79
+ this.authBaseUrl,
80
+ )
81
+ const signature = await signer.signMessage(message)
82
+ const tokenResponse = await this.exchangeSignature(message, signature)
83
+ const token = toAuthToken(tokenResponse)
84
+ this.cachedToken = token
85
+ return token
86
+ }
87
+
88
+ /**
89
+ * Return a valid access token, refreshing automatically if the cached
90
+ * token is expired or about to expire.
91
+ *
92
+ * @throws If no token has been obtained yet via {@link authenticate}.
93
+ */
94
+ async getValidToken(): Promise<AuthToken> {
95
+ if (!this.cachedToken) {
96
+ throw new Error(
97
+ "No auth token available. Call authenticate() with a signer first.",
98
+ )
99
+ }
100
+
101
+ if (this.cachedToken.expiresAt.getTime() - Date.now() < REFRESH_BUFFER_MS) {
102
+ const tokenResponse = await this.refreshToken(
103
+ this.cachedToken.refreshToken,
104
+ )
105
+ this.cachedToken = toAuthToken(tokenResponse)
106
+ }
107
+
108
+ return this.cachedToken
109
+ }
110
+
111
+ /**
112
+ * Revoke an access token.
113
+ */
114
+ async revoke(accessToken: string): Promise<void> {
115
+ const response = await fetch(`${this.authBaseUrl}/api/revoke`, {
116
+ method: "POST",
117
+ headers: { "Content-Type": "application/json" },
118
+ body: JSON.stringify({ token: accessToken }),
119
+ })
120
+ if (!response.ok) {
121
+ throw new Error(
122
+ `Auth server error (${response.status}): ${response.statusText}`,
123
+ )
124
+ }
125
+ if (this.cachedToken?.accessToken === accessToken) {
126
+ this.cachedToken = undefined
127
+ }
128
+ }
129
+
130
+ /** Request a nonce from the auth server. */
131
+ async requestNonce(): Promise<AuthNonceResponse> {
132
+ const response = await fetch(`${this.authBaseUrl}/api/nonce`, {
133
+ method: "GET",
134
+ headers: { Accept: "application/json" },
135
+ })
136
+ if (!response.ok) {
137
+ throw new Error(
138
+ `Auth server error (${response.status}): ${response.statusText}`,
139
+ )
140
+ }
141
+ return response.json() as Promise<AuthNonceResponse>
142
+ }
143
+
144
+ /** Exchange a signed SIWE message for a JWT token. */
145
+ private async exchangeSignature(
146
+ message: string,
147
+ signature: string,
148
+ ): Promise<AuthTokenResponse> {
149
+ const response = await fetch(`${this.authBaseUrl}/api/token`, {
150
+ method: "POST",
151
+ headers: { "Content-Type": "application/json" },
152
+ body: JSON.stringify({ message, signature }),
153
+ })
154
+ if (!response.ok) {
155
+ throw new Error(
156
+ `Auth server error (${response.status}): ${response.statusText}`,
157
+ )
158
+ }
159
+ return response.json() as Promise<AuthTokenResponse>
160
+ }
161
+
162
+ /** Refresh an access token using a refresh token. */
163
+ private async refreshToken(
164
+ refreshTokenValue: string,
165
+ ): Promise<AuthTokenResponse> {
166
+ const response = await fetch(`${this.authBaseUrl}/api/refresh`, {
167
+ method: "POST",
168
+ headers: { "Content-Type": "application/json" },
169
+ body: JSON.stringify({ refresh_token: refreshTokenValue }),
170
+ })
171
+ if (!response.ok) {
172
+ throw new Error(
173
+ `Auth server error (${response.status}): ${response.statusText}`,
174
+ )
175
+ }
176
+ return response.json() as Promise<AuthTokenResponse>
177
+ }
178
+ }
179
+
180
+ /** Validity window (in ms) for a generated SIWE message. */
181
+ const SIWE_MESSAGE_VALIDITY_MS = 10 * 60_000
182
+
183
+ /**
184
+ * Build an EIP-4361 (SIWE) message for OpenSea authentication.
185
+ *
186
+ * @see https://eips.ethereum.org/EIPS/eip-4361
187
+ */
188
+ export function generateSiweMessage(
189
+ address: string,
190
+ scopes: string[],
191
+ nonce: string,
192
+ authBaseUrl: string,
193
+ chainId = 1,
194
+ ): string {
195
+ const url = new URL(authBaseUrl)
196
+ const domain = url.host
197
+ const uri = `${authBaseUrl}/api/token`
198
+ const now = Date.now()
199
+ const issuedAt = new Date(now).toISOString()
200
+ const expirationTime = new Date(now + SIWE_MESSAGE_VALIDITY_MS).toISOString()
201
+ const resources =
202
+ scopes.length > 0
203
+ ? `\nResources:${scopes.map(s => `\n- ${s}`).join("")}`
204
+ : ""
205
+
206
+ return [
207
+ `${domain} wants you to sign in with your Ethereum account:`,
208
+ address,
209
+ "",
210
+ "Sign in to OpenSea",
211
+ "",
212
+ `URI: ${uri}`,
213
+ "Version: 1",
214
+ `Chain ID: ${chainId}`,
215
+ `Nonce: ${nonce}`,
216
+ `Issued At: ${issuedAt}`,
217
+ `Expiration Time: ${expirationTime}`,
218
+ ...(resources ? [resources] : []),
219
+ ].join("\n")
220
+ }
221
+
222
+ /** Convert a raw auth server response to a typed AuthToken. */
223
+ function toAuthToken(response: AuthTokenResponse): AuthToken {
224
+ return {
225
+ accessToken: response.access_token,
226
+ refreshToken: response.refresh_token,
227
+ expiresAt: new Date(Date.now() + response.expires_in * 1000),
228
+ scopes: response.scopes,
229
+ }
230
+ }
@@ -0,0 +1,73 @@
1
+ /**
2
+ * Configuration for the {@link OpenSeaOAuth} helper.
3
+ */
4
+ export interface OpenSeaOAuthConfig {
5
+ /**
6
+ * Public OAuth client id (Zitadel `auth_method: none` + PKCE client).
7
+ * Provisioned via opensea-infrastructure; required.
8
+ */
9
+ clientId: string
10
+ /** Authorization server issuer. Defaults to `https://auth.opensea.io`. */
11
+ issuer?: string
12
+ /**
13
+ * Per-request network timeout in milliseconds for calls to the
14
+ * authorization server. Defaults to 30000 (30s). Guards against a hung
15
+ * connection stalling `opensea login` (or an SDK consumer) indefinitely.
16
+ */
17
+ timeoutMs?: number
18
+ }
19
+
20
+ /**
21
+ * A token set returned by the OAuth 2.1 code/PKCE or device flow.
22
+ */
23
+ export interface OAuthToken {
24
+ /** JWT access token (bearer credential for the OpenSea API). */
25
+ accessToken: string
26
+ /** Refresh token for obtaining a new access token, if granted. */
27
+ refreshToken?: string
28
+ /** OIDC ID token, if `openid` scope was granted. */
29
+ idToken?: string
30
+ /** When the access token expires. */
31
+ expiresAt: Date
32
+ /** Scopes granted to this token. */
33
+ scopes: string[]
34
+ }
35
+
36
+ /**
37
+ * Subset of the OIDC discovery document (`/.well-known/openid-configuration`)
38
+ * this helper relies on.
39
+ */
40
+ export interface OAuthDiscoveryDocument {
41
+ issuer: string
42
+ authorization_endpoint: string
43
+ token_endpoint: string
44
+ device_authorization_endpoint?: string
45
+ revocation_endpoint?: string
46
+ registration_endpoint?: string
47
+ scopes_supported?: string[]
48
+ code_challenge_methods_supported?: string[]
49
+ }
50
+
51
+ /**
52
+ * Raw token response from the OAuth token endpoint.
53
+ */
54
+ export interface OAuthTokenResponse {
55
+ access_token: string
56
+ refresh_token?: string
57
+ id_token?: string
58
+ token_type: string
59
+ expires_in: number
60
+ scope?: string
61
+ }
62
+
63
+ /**
64
+ * Response from the device authorization endpoint (RFC 8628).
65
+ */
66
+ export interface DeviceAuthorizationResponse {
67
+ device_code: string
68
+ user_code: string
69
+ verification_uri: string
70
+ verification_uri_complete?: string
71
+ expires_in: number
72
+ interval?: number
73
+ }