@safepassage/sdk 3.4.9 → 3.4.11

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 (30) hide show
  1. package/README.md +21 -14
  2. package/brands/safepassage/index.d.ts +12 -0
  3. package/brands/safepassage/urls.d.ts +3 -0
  4. package/core/VerificationSDK.d.ts +135 -0
  5. package/index.d.ts +2 -0
  6. package/index.js +1143 -0
  7. package/package.json +14 -47
  8. package/safepassage.min.js +3 -0
  9. package/sdk.min.js +3 -0
  10. package/{dist/types/index.d.ts → types/base.d.ts} +28 -10
  11. package/utils/crypto.d.ts +31 -0
  12. package/utils/environment.d.ts +8 -0
  13. package/{dist/utils → utils}/polyfills.d.ts +1 -2
  14. package/{dist/utils → utils}/security.d.ts +11 -11
  15. package/{dist/utils → utils}/validation.d.ts +9 -12
  16. package/dist/core/SafePassageSDK.d.ts +0 -231
  17. package/dist/core/SafePassageSDK.js +0 -656
  18. package/dist/index.d.ts +0 -21
  19. package/dist/index.js +0 -1100
  20. package/dist/safepassage.min.js +0 -3
  21. package/dist/types/index.js +0 -4
  22. package/dist/utils/__mocks__/polyfills.d.ts +0 -3
  23. package/dist/utils/__mocks__/polyfills.js +0 -10
  24. package/dist/utils/crypto.d.ts +0 -105
  25. package/dist/utils/crypto.js +0 -216
  26. package/dist/utils/environment.d.ts +0 -13
  27. package/dist/utils/environment.js +0 -75
  28. package/dist/utils/polyfills.js +0 -58
  29. package/dist/utils/security.js +0 -190
  30. package/dist/utils/validation.js +0 -158
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # SafePassage SDK v3.4.9
1
+ # SafePassage SDK v3.4.11
2
2
 
3
3
  A lightweight SDK for integrating SafePassage age verification into your website or application.
4
4
 
@@ -14,6 +14,9 @@ A lightweight SDK for integrating SafePassage age verification into your website
14
14
 
15
15
  ## Changelog
16
16
 
17
+ ### 3.4.11
18
+ - Fixed CDN documentation URLs (files are at package root, not `/dist/`)
19
+
17
20
  ### 3.4.9
18
21
  - Prevents `onCancel` from firing after a successful new-tab verification when the popup closes.
19
22
 
@@ -26,7 +29,7 @@ npm install @safepassage/sdk
26
29
  Or load directly from jsDelivr CDN (no bundler required):
27
30
 
28
31
  ```html
29
- <script src="https://cdn.jsdelivr.net/npm/@safepassage/sdk@latest/dist/safepassage.min.js"></script>
32
+ <script src="https://cdn.jsdelivr.net/npm/@safepassage/sdk@latest/safepassage.min.js"></script>
30
33
  ```
31
34
 
32
35
  ## Quick Start
@@ -48,7 +51,7 @@ await sp.verify();
48
51
  ### With CDN (no bundler)
49
52
 
50
53
  ```html
51
- <script src="https://cdn.jsdelivr.net/npm/@safepassage/sdk@latest/dist/safepassage.min.js"></script>
54
+ <script src="https://cdn.jsdelivr.net/npm/@safepassage/sdk@latest/safepassage.min.js"></script>
52
55
  <script>
53
56
  const sp = new SafePassage({
54
57
  apiKey: 'pk_...',
@@ -67,12 +70,13 @@ That's it! The SDK handles session creation automatically.
67
70
  |--------|------|----------|-------------|
68
71
  | apiKey | string | Yes | Your public API key (`pk_...`) |
69
72
  | returnUrl | string | Yes | URL to redirect after verification |
73
+ | cancelUrl | string | No | URL to redirect to if user closes the verification window (new-tab mode) |
70
74
  | environment | string | No | `'production'` or `'staging'` (auto-detected) |
71
75
  | mode | string | No | `'redirect'` (default) or `'new-tab'` |
72
76
  | defaultChallengeAge | number | No | Default minimum age (25 or higher) |
73
77
  | defaultVerificationMode | string | No | `'L1'` or `'L2'` |
74
78
  | onComplete | function | No | Callback for new-tab mode |
75
- | onCancel | function | No | Called when user closes popup (new-tab mode) |
79
+ | onCancel | function | No | Called when user closes popup (new-tab mode). Return `false` to suppress automatic `cancelUrl` redirect. |
76
80
  | onError | function | No | Error handler |
77
81
 
78
82
  ## Verification Options
@@ -119,6 +123,7 @@ Verification opens in a popup window:
119
123
  const sp = new SafePassage({
120
124
  apiKey: 'pk_...',
121
125
  returnUrl: '/age-verified',
126
+ cancelUrl: '/age-cancelled',
122
127
  mode: 'new-tab',
123
128
  onComplete: (result) => {
124
129
  console.log('Verification complete:', result.sessionId, result.status);
@@ -126,6 +131,8 @@ const sp = new SafePassage({
126
131
  },
127
132
  onCancel: () => {
128
133
  console.log('User closed the verification window');
134
+ // Return false if you want to handle navigation manually
135
+ // return false;
129
136
  },
130
137
  onError: (error) => {
131
138
  console.error('Verification error:', error.message);
@@ -135,6 +142,10 @@ const sp = new SafePassage({
135
142
  await sp.verify();
136
143
  ```
137
144
 
145
+ If `cancelUrl` is provided, the SDK will redirect the opener to `cancelUrl` with
146
+ `status=cancelled` and `sessionId` when the user closes the verification window.
147
+ Return `false` from `onCancel` to suppress the automatic redirect.
148
+
138
149
  ## Server-Side Validation (Required!)
139
150
 
140
151
  After verification completes, **always validate the result on your server** before granting access:
@@ -146,7 +157,7 @@ app.get('/age-verified', async (req, res) => {
146
157
 
147
158
  // Validate with your SECRET key (sk_...)
148
159
  const response = await fetch(
149
- `https://api.safepassageapp.com/api/v1/sessions/${sessionId}`,
160
+ `https://api.safepassage.live/api/v1/sessions/${sessionId}`,
150
161
  {
151
162
  headers: {
152
163
  'Authorization': `Bearer ${process.env.SAFEPASSAGE_SECRET_KEY}`
@@ -183,8 +194,6 @@ For reliable verification tracking, configure webhooks in your dashboard:
183
194
  }
184
195
  ```
185
196
 
186
- Webhook `timestamp` values are ISO 8601 strings. SDK `onComplete` results use milliseconds since epoch.
187
-
188
197
  ## Complete Example
189
198
 
190
199
  ### HTML + CDN
@@ -194,7 +203,7 @@ Webhook `timestamp` values are ISO 8601 strings. SDK `onComplete` results use mi
194
203
  <html>
195
204
  <head>
196
205
  <title>Age Verification</title>
197
- <script src="https://cdn.jsdelivr.net/npm/@safepassage/sdk@latest/dist/safepassage.min.js"></script>
206
+ <script src="https://cdn.jsdelivr.net/npm/@safepassage/sdk@latest/safepassage.min.js"></script>
198
207
  </head>
199
208
  <body>
200
209
  <button id="verify-btn">Verify Your Age</button>
@@ -253,8 +262,6 @@ import { SafePassage, SafePassageConfig, VerificationResult } from '@safepassage
253
262
  const config: SafePassageConfig = {
254
263
  apiKey: process.env.NEXT_PUBLIC_SAFEPASSAGE_KEY!,
255
264
  returnUrl: '/verified',
256
- // Optional: used as a fallback redirect for Emblem login failures
257
- cancelUrl: '/verify-cancelled',
258
265
  mode: 'new-tab',
259
266
  onComplete: (result: VerificationResult) => {
260
267
  console.log(`Session ${result.sessionId}: ${result.status}`);
@@ -306,7 +313,7 @@ SafePassage uses two types of API keys:
306
313
  | Public Key | `pk_` | Client-side SDK (this package) |
307
314
  | Secret Key | `sk_` | Server-side validation only |
308
315
 
309
- > **Important**: This SDK only works with public keys (`pk_`). For server-side integrations using secret keys, use the [Direct API](https://docs.safepassageapp.com/api) instead.
316
+ > **Important**: This SDK only works with public keys (`pk_`). For server-side integrations using secret keys, use the [Direct API](https://docs.safepassage.live/api) instead.
310
317
 
311
318
  ## Browser Support
312
319
 
@@ -348,6 +355,6 @@ The SDK now creates sessions automatically via the API when using public keys.
348
355
 
349
356
  ## Support
350
357
 
351
- - [Documentation](https://docs.safepassageapp.com)
352
- - [API Reference](https://docs.safepassageapp.com/api)
353
- - [Dashboard](https://portal.safepassageapp.com)
358
+ - [Documentation](https://docs.safepassage.live)
359
+ - [API Reference](https://docs.safepassage.live/api)
360
+ - [Dashboard](https://portal.safepassage.live)
package/brands/safepassage/index.d.ts ADDED
@@ -0,0 +1,12 @@
1
+ /**
2
+ * SafePassage SDK - Redirect-based age verification
3
+ */
4
+ import { VerificationSDK } from '../../core/VerificationSDK';
5
+ import type { SDKConfig, VerificationOptions, VerificationResult, SessionValidationResponse, SessionCreationResponse, CreateSessionRequest } from '../../types/base';
6
+ export type SafePassageConfig = SDKConfig;
7
+ export declare class SafePassage extends VerificationSDK {
8
+ constructor(config: SafePassageConfig);
9
+ }
10
+ export declare const VERSION = "3.4.9";
11
+ export type { SDKConfig, VerificationOptions, VerificationResult, SessionValidationResponse, SessionCreationResponse, CreateSessionRequest, };
12
+ export default SafePassage;
package/brands/safepassage/urls.d.ts ADDED
@@ -0,0 +1,3 @@
1
+ import type { BrandUrls, BrandConstants } from '../../core/VerificationSDK';
2
+ export declare const BRAND_URLS: BrandUrls;
3
+ export declare const BRAND_CONSTANTS: BrandConstants;
package/core/VerificationSDK.d.ts ADDED
@@ -0,0 +1,135 @@
1
+ /**
2
+ * Verification SDK - Redirect-based age verification
3
+ *
4
+ * Lightweight SDK for integrating age verification using redirect flow.
5
+ * Provides a secure, easy-to-implement solution with comprehensive
6
+ * security features and flexible integration options.
7
+ */
8
+ import type { SDKConfig, VerificationOptions } from '../types/base';
9
+ export interface UrlConfig {
10
+ apiUrl: string;
11
+ verifyUiUrl: string;
12
+ engineUrl: string;
13
+ wsUrl: string;
14
+ trustedOrigins: string[];
15
+ }
16
+ export interface BrandUrls {
17
+ production: UrlConfig;
18
+ staging: UrlConfig;
19
+ }
20
+ export interface BrandConstants {
21
+ name: string;
22
+ hmacSecretProd: string;
23
+ hmacSecretStaging: string;
24
+ messageType: string;
25
+ legacyMessageType?: string;
26
+ popupName: string;
27
+ docsUrl: string;
28
+ }
29
+ /**
30
+ * SDK Main Class
31
+ *
32
+ * Primary SDK class that manages verification sessions with comprehensive
33
+ * security and error handling. Supports both redirect and new-tab modes with
34
+ * automatic session management and PostMessage communication.
35
+ */
36
+ export declare class VerificationSDK {
37
+ private config;
38
+ private readonly brandUrls;
39
+ private readonly brandConstants;
40
+ private popupWindow;
41
+ private messageListener;
42
+ private popupMonitorInterval;
43
+ private unloadListener;
44
+ private isVerificationInProgress;
45
+ private currentSessionId;
46
+ private hasReceivedResult;
47
+ private lastVerifyUrl;
48
+ private lastSessionToken;
49
+ private lastExternalUserId;
50
+ private lastSandboxMode;
51
+ private temporaryHandoffToken;
52
+ private static readonly LOCAL_HOSTNAMES;
53
+ /**
54
+ * Initialize SDK
55
+ *
56
+ * Validates configuration, sets up security measures, and prepares the SDK
57
+ * for verification operations. Performs comprehensive environment validation
58
+ * and security initialization.
59
+ */
60
+ constructor(config: SDKConfig, brandUrls: BrandUrls, brandConstants: BrandConstants);
61
+ /**
62
+ * Initiate verification with race condition protection
63
+ */
64
+ verify(options?: VerificationOptions): Promise<void>;
65
+ /**
66
+ * Build verification URL with HMAC-signed state
67
+ */
68
+ private buildVerificationUrl;
69
+ /**
70
+ * Redirect in same tab
71
+ */
72
+ private redirect;
73
+ /**
74
+ * Open in new tab with PostMessage communication and proper cleanup
75
+ */
76
+ private openNewTab;
77
+ /**
78
+ * Set up automatic cleanup on page unload to prevent memory leaks
79
+ */
80
+ private setupAutoCleanup;
81
+ /**
82
+ * Auto-detect environment based on current URL
83
+ */
84
+ private detectEnvironment;
85
+ /**
86
+ * Get the current environment
87
+ */
88
+ getEnvironment(): 'production' | 'staging';
89
+ /**
90
+ * Unlock verification process to allow new verifications
91
+ */
92
+ private unlockVerification;
93
+ /**
94
+ * Internal cleanup method to prevent memory leaks
95
+ */
96
+ private cleanup;
97
+ private handleCancellation;
98
+ private redirectToCancelUrl;
99
+ /**
100
+ * Remove auto-cleanup listeners
101
+ */
102
+ private removeAutoCleanupListeners;
103
+ /**
104
+ * Public cleanup method for manual resource management
105
+ */
106
+ destroy(): void;
107
+ /**
108
+ * Get Portal API URL based on environment and brand
109
+ */
110
+ private getPortalApiUrl;
111
+ /**
112
+ * Get Engine URL based on environment and brand
113
+ */
114
+ private getEngineUrl;
115
+ /**
116
+ * Get WebSocket URL based on environment and brand
117
+ */
118
+ private getWebSocketUrl;
119
+ /**
120
+ * Detect if this is a public key (pk_ prefix) vs private key (sk_ prefix)
121
+ */
122
+ private isPublicKey;
123
+ /**
124
+ * Create session internally for public keys
125
+ */
126
+ private createInternalSession;
127
+ private isBillingBlockError;
128
+ private openBillingBlockPage;
129
+ private getUrlConfig;
130
+ private getTrustedOrigins;
131
+ private getAllowedCustomOrigins;
132
+ private getLocalOrigin;
133
+ private applyLocalVerifyOverride;
134
+ private getHmacSecret;
135
+ }
package/index.d.ts ADDED
@@ -0,0 +1,2 @@
1
+ export * from './brands/safepassage';
2
+ export { default } from './brands/safepassage';