@opensea/sdk 11.1.0 → 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 +46 -12
  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 +51 -11
  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,168 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.OpenSeaAuth = void 0;
4
+ exports.generateSiweMessage = generateSiweMessage;
5
+ const DEFAULT_AUTH_BASE_URL = "https://auth.opensea.io";
6
+ /** Buffer (in ms) before expiry at which auto-refresh triggers. */
7
+ const REFRESH_BUFFER_MS = 60_000;
8
+ /**
9
+ * SIWE-based authentication helper for OpenSea.
10
+ *
11
+ * Handles the full sign-in flow: nonce request, EIP-4361 message generation,
12
+ * signature exchange, token caching, and automatic refresh.
13
+ *
14
+ * @example
15
+ * ```ts
16
+ * import { OpenSeaAuth } from "@opensea/sdk"
17
+ *
18
+ * const auth = new OpenSeaAuth()
19
+ * const token = await auth.authenticate(signer, {
20
+ * scopes: ["read:eligibility", "write:orders"],
21
+ * })
22
+ *
23
+ * // Auto-refresh before expiry
24
+ * const freshToken = await auth.getValidToken()
25
+ *
26
+ * // Revoke
27
+ * await auth.revoke(token.accessToken)
28
+ * ```
29
+ *
30
+ * @category Authentication
31
+ */
32
+ class OpenSeaAuth {
33
+ authBaseUrl;
34
+ cachedToken;
35
+ constructor(config = {}) {
36
+ this.authBaseUrl = (config.authBaseUrl ?? DEFAULT_AUTH_BASE_URL).replace(/\/$/, "");
37
+ }
38
+ /**
39
+ * Run the full SIWE authentication flow:
40
+ * 1. Request a nonce from the auth server
41
+ * 2. Build an EIP-4361 SIWE message
42
+ * 3. Sign it with the provided signer
43
+ * 4. Exchange the signature for a scoped JWT token
44
+ *
45
+ * The returned token is cached in memory and will be auto-refreshed
46
+ * by {@link getValidToken}.
47
+ */
48
+ async authenticate(signer, options = {}) {
49
+ const address = await signer.getAddress();
50
+ const { nonce } = await this.requestNonce();
51
+ const message = generateSiweMessage(address, options.scopes ?? [], nonce, this.authBaseUrl);
52
+ const signature = await signer.signMessage(message);
53
+ const tokenResponse = await this.exchangeSignature(message, signature);
54
+ const token = toAuthToken(tokenResponse);
55
+ this.cachedToken = token;
56
+ return token;
57
+ }
58
+ /**
59
+ * Return a valid access token, refreshing automatically if the cached
60
+ * token is expired or about to expire.
61
+ *
62
+ * @throws If no token has been obtained yet via {@link authenticate}.
63
+ */
64
+ async getValidToken() {
65
+ if (!this.cachedToken) {
66
+ throw new Error("No auth token available. Call authenticate() with a signer first.");
67
+ }
68
+ if (this.cachedToken.expiresAt.getTime() - Date.now() < REFRESH_BUFFER_MS) {
69
+ const tokenResponse = await this.refreshToken(this.cachedToken.refreshToken);
70
+ this.cachedToken = toAuthToken(tokenResponse);
71
+ }
72
+ return this.cachedToken;
73
+ }
74
+ /**
75
+ * Revoke an access token.
76
+ */
77
+ async revoke(accessToken) {
78
+ const response = await fetch(`${this.authBaseUrl}/api/revoke`, {
79
+ method: "POST",
80
+ headers: { "Content-Type": "application/json" },
81
+ body: JSON.stringify({ token: accessToken }),
82
+ });
83
+ if (!response.ok) {
84
+ throw new Error(`Auth server error (${response.status}): ${response.statusText}`);
85
+ }
86
+ if (this.cachedToken?.accessToken === accessToken) {
87
+ this.cachedToken = undefined;
88
+ }
89
+ }
90
+ /** Request a nonce from the auth server. */
91
+ async requestNonce() {
92
+ const response = await fetch(`${this.authBaseUrl}/api/nonce`, {
93
+ method: "GET",
94
+ headers: { Accept: "application/json" },
95
+ });
96
+ if (!response.ok) {
97
+ throw new Error(`Auth server error (${response.status}): ${response.statusText}`);
98
+ }
99
+ return response.json();
100
+ }
101
+ /** Exchange a signed SIWE message for a JWT token. */
102
+ async exchangeSignature(message, signature) {
103
+ const response = await fetch(`${this.authBaseUrl}/api/token`, {
104
+ method: "POST",
105
+ headers: { "Content-Type": "application/json" },
106
+ body: JSON.stringify({ message, signature }),
107
+ });
108
+ if (!response.ok) {
109
+ throw new Error(`Auth server error (${response.status}): ${response.statusText}`);
110
+ }
111
+ return response.json();
112
+ }
113
+ /** Refresh an access token using a refresh token. */
114
+ async refreshToken(refreshTokenValue) {
115
+ const response = await fetch(`${this.authBaseUrl}/api/refresh`, {
116
+ method: "POST",
117
+ headers: { "Content-Type": "application/json" },
118
+ body: JSON.stringify({ refresh_token: refreshTokenValue }),
119
+ });
120
+ if (!response.ok) {
121
+ throw new Error(`Auth server error (${response.status}): ${response.statusText}`);
122
+ }
123
+ return response.json();
124
+ }
125
+ }
126
+ exports.OpenSeaAuth = OpenSeaAuth;
127
+ /** Validity window (in ms) for a generated SIWE message. */
128
+ const SIWE_MESSAGE_VALIDITY_MS = 10 * 60_000;
129
+ /**
130
+ * Build an EIP-4361 (SIWE) message for OpenSea authentication.
131
+ *
132
+ * @see https://eips.ethereum.org/EIPS/eip-4361
133
+ */
134
+ function generateSiweMessage(address, scopes, nonce, authBaseUrl, chainId = 1) {
135
+ const url = new URL(authBaseUrl);
136
+ const domain = url.host;
137
+ const uri = `${authBaseUrl}/api/token`;
138
+ const now = Date.now();
139
+ const issuedAt = new Date(now).toISOString();
140
+ const expirationTime = new Date(now + SIWE_MESSAGE_VALIDITY_MS).toISOString();
141
+ const resources = scopes.length > 0
142
+ ? `\nResources:${scopes.map(s => `\n- ${s}`).join("")}`
143
+ : "";
144
+ return [
145
+ `${domain} wants you to sign in with your Ethereum account:`,
146
+ address,
147
+ "",
148
+ "Sign in to OpenSea",
149
+ "",
150
+ `URI: ${uri}`,
151
+ "Version: 1",
152
+ `Chain ID: ${chainId}`,
153
+ `Nonce: ${nonce}`,
154
+ `Issued At: ${issuedAt}`,
155
+ `Expiration Time: ${expirationTime}`,
156
+ ...(resources ? [resources] : []),
157
+ ].join("\n");
158
+ }
159
+ /** Convert a raw auth server response to a typed AuthToken. */
160
+ function toAuthToken(response) {
161
+ return {
162
+ accessToken: response.access_token,
163
+ refreshToken: response.refresh_token,
164
+ expiresAt: new Date(Date.now() + response.expires_in * 1000),
165
+ scopes: response.scopes,
166
+ };
167
+ }
168
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,69 @@
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
+ * A token set returned by the OAuth 2.1 code/PKCE or device flow.
21
+ */
22
+ export interface OAuthToken {
23
+ /** JWT access token (bearer credential for the OpenSea API). */
24
+ accessToken: string;
25
+ /** Refresh token for obtaining a new access token, if granted. */
26
+ refreshToken?: string;
27
+ /** OIDC ID token, if `openid` scope was granted. */
28
+ idToken?: string;
29
+ /** When the access token expires. */
30
+ expiresAt: Date;
31
+ /** Scopes granted to this token. */
32
+ scopes: string[];
33
+ }
34
+ /**
35
+ * Subset of the OIDC discovery document (`/.well-known/openid-configuration`)
36
+ * this helper relies on.
37
+ */
38
+ export interface OAuthDiscoveryDocument {
39
+ issuer: string;
40
+ authorization_endpoint: string;
41
+ token_endpoint: string;
42
+ device_authorization_endpoint?: string;
43
+ revocation_endpoint?: string;
44
+ registration_endpoint?: string;
45
+ scopes_supported?: string[];
46
+ code_challenge_methods_supported?: string[];
47
+ }
48
+ /**
49
+ * Raw token response from the OAuth token endpoint.
50
+ */
51
+ export interface OAuthTokenResponse {
52
+ access_token: string;
53
+ refresh_token?: string;
54
+ id_token?: string;
55
+ token_type: string;
56
+ expires_in: number;
57
+ scope?: string;
58
+ }
59
+ /**
60
+ * Response from the device authorization endpoint (RFC 8628).
61
+ */
62
+ export interface DeviceAuthorizationResponse {
63
+ device_code: string;
64
+ user_code: string;
65
+ verification_uri: string;
66
+ verification_uri_complete?: string;
67
+ expires_in: number;
68
+ interval?: number;
69
+ }
@@ -0,0 +1,3 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ //# sourceMappingURL=oauth-types.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"oauth-types.js","sourceRoot":"","sources":["../../src/auth/oauth-types.ts"],"names":[],"mappings":""}
@@ -0,0 +1,109 @@
1
+ import type { DeviceAuthorizationResponse, OAuthDiscoveryDocument, OAuthToken, OpenSeaOAuthConfig } from "./oauth-types";
2
+ /**
3
+ * OAuth 2.1 authorization-code + PKCE helper for OpenSea (OS2-33722).
4
+ *
5
+ * Runs the standard flow against the OpenSea authorization server (Zitadel at
6
+ * `auth.opensea.io`) using a public client — no client secret, no private key,
7
+ * no SIWE message signing. This is the same flow spec-compliant MCP clients
8
+ * discover via the MCP server's Protected Resource Metadata, exposed here for
9
+ * programmatic consumers (the CLI's keyless `opensea login` is built on it).
10
+ *
11
+ * Endpoints are resolved from OIDC discovery
12
+ * (`/.well-known/openid-configuration`) rather than hardcoded.
13
+ *
14
+ * @example
15
+ * ```ts
16
+ * const oauth = new OpenSeaOAuth({ clientId: "..." })
17
+ *
18
+ * // Authorization code + PKCE (browser-capable environments)
19
+ * const req = await oauth.createAuthorizationRequest({
20
+ * redirectUri: "http://127.0.0.1:8151/callback",
21
+ * scopes: ["read:eligibility"],
22
+ * })
23
+ * // ...direct the user to req.url, receive `code` + `state` on the redirect...
24
+ * const token = await oauth.exchangeCode({
25
+ * code,
26
+ * codeVerifier: req.codeVerifier,
27
+ * redirectUri: "http://127.0.0.1:8151/callback",
28
+ * })
29
+ *
30
+ * // Device flow (headless environments)
31
+ * const device = await oauth.requestDeviceAuthorization()
32
+ * // ...show device.user_code + device.verification_uri to the user...
33
+ * const token2 = await oauth.pollDeviceToken(device)
34
+ * ```
35
+ *
36
+ * @category Authentication
37
+ */
38
+ export declare class OpenSeaOAuth {
39
+ private readonly issuer;
40
+ private readonly clientId;
41
+ private readonly timeoutMs;
42
+ private discovery;
43
+ constructor(config: OpenSeaOAuthConfig);
44
+ /**
45
+ * Fetch (and cache) the OIDC discovery document for the issuer, then
46
+ * validate it: the advertised `issuer` must match the configured issuer
47
+ * (OpenID Connect Discovery §4.3 / OAuth 2.1 mix-up defense) and the
48
+ * authorization/token endpoints must be secure (`https:`, or loopback for
49
+ * local testing). This prevents a compromised discovery response from
50
+ * redirecting the flow to an attacker-controlled endpoint.
51
+ */
52
+ getDiscovery(): Promise<OAuthDiscoveryDocument>;
53
+ /**
54
+ * Build an authorization request for the code + PKCE flow. Returns the URL
55
+ * to open in a browser plus the `codeVerifier` and `state` the caller must
56
+ * hold on to for {@link exchangeCode} and redirect validation.
57
+ */
58
+ createAuthorizationRequest(options: {
59
+ redirectUri: string;
60
+ scopes?: string[];
61
+ }): Promise<{
62
+ url: string;
63
+ codeVerifier: string;
64
+ state: string;
65
+ }>;
66
+ /** Exchange an authorization code (plus PKCE verifier) for tokens. */
67
+ exchangeCode(options: {
68
+ code: string;
69
+ codeVerifier: string;
70
+ redirectUri: string;
71
+ }): Promise<OAuthToken>;
72
+ /** Refresh an access token using a refresh token. */
73
+ refresh(refreshToken: string): Promise<OAuthToken>;
74
+ /** Revoke an access or refresh token. */
75
+ revoke(token: string): Promise<void>;
76
+ /**
77
+ * Start a device authorization flow (RFC 8628) — for headless environments
78
+ * where a browser redirect is not possible.
79
+ */
80
+ requestDeviceAuthorization(options?: {
81
+ scopes?: string[];
82
+ }): Promise<DeviceAuthorizationResponse>;
83
+ /**
84
+ * Poll the token endpoint until the user completes device authorization.
85
+ * Respects the server-provided `interval` and `slow_down` responses, and
86
+ * stops when `expires_in` elapses.
87
+ */
88
+ pollDeviceToken(device: DeviceAuthorizationResponse): Promise<OAuthToken>;
89
+ private postToken;
90
+ /**
91
+ * `fetch` wrapper that aborts the request after `this.timeoutMs`, so a hung
92
+ * authorization server can't stall the flow indefinitely.
93
+ */
94
+ private fetchWithTimeout;
95
+ }
96
+ /**
97
+ * Read the wallet address from decoded JWT claims. Zitadel injects it as a
98
+ * top-level `wallet` claim (plaintext) via the `inject_wallet_claim` action —
99
+ * the same claim `opensea-mcp` and the os2-core REST API read. `sub` is the
100
+ * fallback identifier (the Zitadel account id) when no wallet claim is present.
101
+ * Returns `undefined` if neither is available.
102
+ */
103
+ export declare function extractWalletAddress(claims: Record<string, unknown>): string | undefined;
104
+ /**
105
+ * Decode a JWT payload without verifying the signature. Intended for reading
106
+ * claims out of a token the authorization server just issued to us over TLS —
107
+ * NOT for validating inbound tokens.
108
+ */
109
+ export declare function decodeJwtPayload(token: string): Record<string, unknown>;