@soliton-id/web-sdk 1.2.0 → 1.4.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.
package/dist/index.mjs CHANGED
@@ -1,69 +1,206 @@
1
1
  /* Soliton Web SDK v1. Built from sdk/src via `npm run build:sdk`; do not edit by hand. */
2
2
 
3
- // sdk/src/trustedOrigin.ts
4
- function trustedOrigin(value) {
5
- const url = new URL(value);
6
- const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
7
- if (url.origin !== value || url.username || url.password || value.includes("*") || url.protocol !== "https:" && !(url.protocol === "http:" && local)) {
8
- throw new Error("Use an exact HTTPS origin (HTTP loopback is allowed for development)");
3
+ // sdk/src/theme.ts
4
+ var MAX_THEME_PARAM_LENGTH = 4096;
5
+ var COLOR_KEYS = {
6
+ background: true,
7
+ surface: true,
8
+ surfaceMuted: true,
9
+ text: true,
10
+ textMuted: true,
11
+ border: true,
12
+ primary: true,
13
+ primaryPressed: true,
14
+ onPrimary: true,
15
+ accent: true,
16
+ progress: true,
17
+ success: true,
18
+ warning: true,
19
+ error: true,
20
+ illustration: true,
21
+ overlay: true,
22
+ cameraBackground: true,
23
+ oval: true,
24
+ ovalProgress: true,
25
+ closeButton: true
26
+ };
27
+ var COLOR_KEY_ORDER = Object.keys(COLOR_KEYS);
28
+ var COLOR_SCHEMES = ["auto", "light", "dark"];
29
+ var HEX_COLOR_RE = /^#(?:[0-9a-f]{3}|[0-9a-f]{6})$/i;
30
+ var MAX_LISTED = 20;
31
+ var MAX_LISTED_NAME = 40;
32
+ var hasOwn = (object, key) => Object.prototype.hasOwnProperty.call(object, key);
33
+ function isRecord(value) {
34
+ return typeof value === "object" && value !== null && !Array.isArray(value);
35
+ }
36
+ function isUnset(value) {
37
+ return value === void 0 || value === null;
38
+ }
39
+ function isHexColor(value) {
40
+ return typeof value === "string" && value.length <= 7 && HEX_COLOR_RE.test(value);
41
+ }
42
+ function filterPalette(value, path, ignored) {
43
+ if (!isRecord(value)) {
44
+ ignored.push(path);
45
+ return void 0;
9
46
  }
10
- return url.origin;
47
+ const valid = {};
48
+ for (const key of Object.keys(value)) {
49
+ const color = value[key];
50
+ if (isUnset(color)) continue;
51
+ if (hasOwn(COLOR_KEYS, key) && isHexColor(color)) {
52
+ valid[key] = color;
53
+ } else {
54
+ ignored.push(`${path}.${key}`);
55
+ }
56
+ }
57
+ const out = {};
58
+ let kept = false;
59
+ for (const key of COLOR_KEY_ORDER) {
60
+ const color = valid[key];
61
+ if (color !== void 0) {
62
+ out[key] = color;
63
+ kept = true;
64
+ }
65
+ }
66
+ return kept ? out : void 0;
11
67
  }
12
-
13
- // sdk/src/hostedUrl.ts
14
- var HOSTED_PATH_RE = /^\/v\/[0-9a-f]{32}$/;
15
- var ALLOWED_HTTPS_ORIGINS = /* @__PURE__ */ new Set([
16
- "https://soliton.id",
17
- "https://staging.soliton.id"
18
- ]);
19
- function parseHostedUrl(raw, verificationOrigin) {
20
- const configuredOrigin = verificationOrigin === void 0 ? void 0 : trustedOrigin(verificationOrigin);
21
- let url;
68
+ function filterTheme(input, ignored) {
69
+ let colorScheme;
70
+ let colors;
71
+ let darkColors;
72
+ for (const key of Object.keys(input)) {
73
+ const value = input[key];
74
+ if (isUnset(value)) continue;
75
+ if (key === "colorScheme") {
76
+ if (typeof value === "string" && COLOR_SCHEMES.indexOf(value) !== -1) {
77
+ colorScheme = value;
78
+ } else {
79
+ ignored.push(key);
80
+ }
81
+ } else if (key === "colors") {
82
+ colors = filterPalette(value, key, ignored);
83
+ } else if (key === "darkColors") {
84
+ darkColors = filterPalette(value, key, ignored);
85
+ } else {
86
+ ignored.push(key);
87
+ }
88
+ }
89
+ if (colorScheme === void 0 && colors === void 0 && darkColors === void 0) {
90
+ return null;
91
+ }
92
+ const theme = {};
93
+ if (colorScheme !== void 0) theme.colorScheme = colorScheme;
94
+ if (colors !== void 0) theme.colors = colors;
95
+ if (darkColors !== void 0) theme.darkColors = darkColors;
96
+ return theme;
97
+ }
98
+ function listNames(names) {
99
+ const shown = names.slice(0, MAX_LISTED).map((name) => name.length > MAX_LISTED_NAME ? `${name.slice(0, MAX_LISTED_NAME)}...` : name);
100
+ const more = names.length - shown.length;
101
+ return shown.join(", ") + (more > 0 ? ` and ${more} more` : "");
102
+ }
103
+ function warn(message) {
22
104
  try {
23
- url = new URL(raw);
105
+ if (typeof console !== "undefined" && typeof console.warn === "function") {
106
+ console.warn(message);
107
+ }
24
108
  } catch (e) {
25
- throw new Error(`SolitonVerify: "url" is not a valid absolute URL`);
26
- }
27
- const isLocalHttp = url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1");
28
- if (configuredOrigin !== void 0 && url.origin !== configuredOrigin) {
29
- throw new Error('SolitonVerify: "url" does not match the configured verificationOrigin');
30
109
  }
31
- if (configuredOrigin === void 0 && !ALLOWED_HTTPS_ORIGINS.has(url.origin) && !isLocalHttp) {
32
- throw new Error(
33
- 'SolitonVerify: "url" must be hosted on https://soliton.id or https://staging.soliton.id (http is allowed for localhost/127.0.0.1 development only)'
34
- );
110
+ }
111
+ function prepareTheme(source, warnPrefix, maxLength = MAX_THEME_PARAM_LENGTH) {
112
+ const ignored = [];
113
+ let theme = null;
114
+ let whole = "";
115
+ try {
116
+ const input = source.theme;
117
+ if (isUnset(input)) return { theme: null, param: null };
118
+ if (isRecord(input)) {
119
+ theme = filterTheme(input, ignored);
120
+ } else {
121
+ whole = "it is not an object";
122
+ }
123
+ } catch (e) {
124
+ theme = null;
125
+ whole = "it could not be read";
35
126
  }
36
- if (url.username || url.password) {
37
- throw new Error('SolitonVerify: "url" must not embed credentials');
127
+ let param = null;
128
+ if (theme !== null) {
129
+ const json = JSON.stringify(theme);
130
+ if (json.length > maxLength) {
131
+ theme = null;
132
+ whole = `it is longer than ${maxLength} characters`;
133
+ } else {
134
+ param = json;
135
+ }
38
136
  }
39
- if (!HOSTED_PATH_RE.test(url.pathname)) {
40
- throw new Error(
41
- 'SolitonVerify: "url" does not look like a hosted verification URL (/v/{token})'
137
+ if (whole !== "") {
138
+ warn(`${warnPrefix} theme ignored: ${whole}.`);
139
+ } else if (ignored.length > 0) {
140
+ warn(
141
+ `${warnPrefix} theme: ignored ${listNames(ignored)}. Colors must be "#rgb" or "#rrggbb" and colorScheme "auto", "light" or "dark".`
42
142
  );
43
143
  }
44
- return { url, hostedOrigin: url.origin };
144
+ return { theme, param };
145
+ }
146
+ function prefersDark() {
147
+ try {
148
+ return typeof window !== "undefined" && typeof window.matchMedia === "function" && window.matchMedia("(prefers-color-scheme: dark)").matches === true;
149
+ } catch (e) {
150
+ return false;
151
+ }
152
+ }
153
+ function activePalette(theme) {
154
+ var _a;
155
+ if (theme === null) return void 0;
156
+ const scheme = (_a = theme.colorScheme) != null ? _a : "auto";
157
+ const dark = scheme === "dark" || scheme === "auto" && prefersDark();
158
+ return dark ? theme.darkColors : theme.colors;
159
+ }
160
+ function relativeLuminance(hex) {
161
+ const digits = hex.length === 4 ? hex.slice(1).split("").map((digit) => digit + digit).join("") : hex.slice(1);
162
+ const channel = (offset) => {
163
+ const value = parseInt(digits.slice(offset, offset + 2), 16) / 255;
164
+ return value <= 0.04045 ? value / 12.92 : Math.pow((value + 0.055) / 1.055, 2.4);
165
+ };
166
+ return 0.2126 * channel(0) + 0.7152 * channel(2) + 0.0722 * channel(4);
167
+ }
168
+ function contrastRatio(a, b) {
169
+ const la = relativeLuminance(a);
170
+ const lb = relativeLuminance(b);
171
+ return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
45
172
  }
46
173
 
47
174
  // sdk/src/overlay.ts
48
175
  var MAX_Z_INDEX = "2147483647";
176
+ var DEFAULT_BACKDROP = "#0f110b";
177
+ var DEFAULT_CLOSE_FILL = "rgba(0,0,0,0.45)";
178
+ var LIGHT_INK = { hex: "#ffffff", rgb: "255,255,255" };
179
+ var DARK_INK = { hex: DEFAULT_BACKDROP, rgb: "15,17,11" };
180
+ function inkOn(backdrop) {
181
+ return contrastRatio(DARK_INK.hex, backdrop) > contrastRatio(LIGHT_INK.hex, backdrop) ? DARK_INK.rgb : LIGHT_INK.rgb;
182
+ }
49
183
  var openOverlayCount = 0;
50
184
  var savedBodyOverflow = "";
51
- function createOverlay(iframeSrc, onCloseClick) {
185
+ function createOverlay(iframeSrc, onCloseClick, names, backdrop, closeFill) {
186
+ const background = backdrop != null ? backdrop : DEFAULT_BACKDROP;
187
+ const ink = backdrop === void 0 ? LIGHT_INK.rgb : inkOn(backdrop);
188
+ const closeInk = closeFill === void 0 ? LIGHT_INK.rgb : inkOn(closeFill);
52
189
  const doc = document;
53
190
  const container = doc.createElement("div");
54
- container.setAttribute("data-soliton-sdk", "overlay");
191
+ container.setAttribute(names.marker, "overlay");
55
192
  container.style.cssText = [
56
193
  "position:fixed",
57
194
  "inset:0",
58
195
  `z-index:${MAX_Z_INDEX}`,
59
- "background:#0f110b",
196
+ `background:${background}`,
60
197
  "display:block"
61
198
  ].join(";");
62
199
  const style = doc.createElement("style");
63
- style.textContent = "@keyframes soliton-sdk-spin{to{transform:rotate(360deg)}}";
200
+ style.textContent = `@keyframes ${names.animation}{to{transform:rotate(360deg)}}`;
64
201
  container.appendChild(style);
65
202
  const loading = doc.createElement("div");
66
- loading.setAttribute("data-soliton-sdk", "loading");
203
+ loading.setAttribute(names.marker, "loading");
67
204
  loading.style.cssText = [
68
205
  "position:absolute",
69
206
  "inset:0",
@@ -72,7 +209,7 @@ function createOverlay(iframeSrc, onCloseClick) {
72
209
  "align-items:center",
73
210
  "justify-content:center",
74
211
  "gap:14px",
75
- "color:rgba(255,255,255,0.75)",
212
+ `color:rgba(${ink},0.75)`,
76
213
  "font:14px/1.4 -apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif"
77
214
  ].join(";");
78
215
  const spinner = doc.createElement("div");
@@ -80,9 +217,9 @@ function createOverlay(iframeSrc, onCloseClick) {
80
217
  "width:22px",
81
218
  "height:22px",
82
219
  "border-radius:999px",
83
- "border:2px solid rgba(255,255,255,0.25)",
84
- "border-top-color:rgba(255,255,255,0.9)",
85
- "animation:soliton-sdk-spin 0.8s linear infinite"
220
+ `border:2px solid rgba(${ink},0.25)`,
221
+ `border-top-color:rgba(${ink},0.9)`,
222
+ `animation:${names.animation} 0.8s linear infinite`
86
223
  ].join(";");
87
224
  const loadingText = doc.createElement("div");
88
225
  loadingText.textContent = "Loading secure verification...";
@@ -91,7 +228,7 @@ function createOverlay(iframeSrc, onCloseClick) {
91
228
  container.appendChild(loading);
92
229
  const iframe = doc.createElement("iframe");
93
230
  iframe.setAttribute("allow", "camera; microphone; fullscreen; autoplay");
94
- iframe.setAttribute("title", "Soliton identity verification");
231
+ iframe.setAttribute("title", names.title);
95
232
  iframe.style.cssText = [
96
233
  "position:absolute",
97
234
  "inset:0",
@@ -113,9 +250,9 @@ function createOverlay(iframeSrc, onCloseClick) {
113
250
  "width:36px",
114
251
  "height:36px",
115
252
  "border-radius:999px",
116
- "border:1px solid rgba(255,255,255,0.3)",
117
- "background:rgba(0,0,0,0.45)",
118
- "color:rgba(255,255,255,0.85)",
253
+ `border:1px solid rgba(${closeInk},0.3)`,
254
+ `background:${closeFill != null ? closeFill : DEFAULT_CLOSE_FILL}`,
255
+ `color:rgba(${closeInk},0.85)`,
119
256
  "font:20px/1 -apple-system,BlinkMacSystemFont,'Segoe UI',sans-serif",
120
257
  "cursor:pointer",
121
258
  "padding:0"
@@ -146,43 +283,51 @@ function createOverlay(iframeSrc, onCloseClick) {
146
283
  };
147
284
  }
148
285
 
149
- // sdk/src/types.ts
150
- var EMBED_PROTOCOL = "soliton-v1";
151
-
152
- // sdk/src/index.ts
286
+ // sdk/src/core.ts
153
287
  var AUTO_CLOSE_DELAY_MS = 250;
154
288
  var HELLO_INTERVAL_MS = 250;
155
289
  var HELLO_MAX_PINGS = 40;
156
290
  var READY_TIMEOUT_MS = 3e4;
157
- function open(options) {
291
+ function openOverlay(options, names, parseUrl) {
292
+ var _a;
158
293
  if (!options || typeof options.url !== "string") {
159
- throw new Error('SolitonVerify: open() requires an options object with a "url"');
294
+ throw new Error(`${names.errorPrefix} open() requires an options object with a "url"`);
160
295
  }
161
296
  if (typeof options.onComplete !== "function") {
162
- throw new Error("SolitonVerify: open() requires an onComplete callback");
297
+ throw new Error(`${names.errorPrefix} open() requires an onComplete callback`);
163
298
  }
164
- const { url, hostedOrigin } = parseHostedUrl(options.url, options.verificationOrigin);
299
+ const { url, hostedOrigin } = parseUrl(options.url, options.verificationOrigin);
165
300
  const src = new URL(url.toString());
166
301
  src.searchParams.set("mode", "embed");
167
302
  src.searchParams.set("sdk", "1");
303
+ for (const [key, value] of (_a = names.params) != null ? _a : []) src.searchParams.set(key, value);
168
304
  if (options.locale) src.searchParams.set("locale", options.locale);
305
+ const theme = prepareTheme(options, names.errorPrefix);
306
+ if (theme.param !== null) src.searchParams.set("theme", theme.param);
169
307
  let closed = false;
170
308
  let terminalDelivered = false;
171
309
  let loadTimedOut = false;
172
310
  let autoCloseTimer = null;
173
311
  let readyTimer = null;
174
- const overlay = createOverlay(src.toString(), () => close());
312
+ const palette = activePalette(theme.theme);
313
+ const overlay = createOverlay(
314
+ src.toString(),
315
+ () => close(),
316
+ names.overlay,
317
+ palette == null ? void 0 : palette.overlay,
318
+ palette == null ? void 0 : palette.closeButton
319
+ );
175
320
  let helloPings = 0;
176
321
  const postHello = () => {
177
- var _a;
322
+ var _a2;
178
323
  helloPings += 1;
179
324
  if (helloPings > HELLO_MAX_PINGS) {
180
325
  stopHello();
181
326
  return;
182
327
  }
183
328
  try {
184
- (_a = overlay.iframe.contentWindow) == null ? void 0 : _a.postMessage(
185
- { protocol: EMBED_PROTOCOL, type: "soliton:hello" },
329
+ (_a2 = overlay.iframe.contentWindow) == null ? void 0 : _a2.postMessage(
330
+ { protocol: names.protocol, type: names.hello },
186
331
  hostedOrigin
187
332
  );
188
333
  } catch (e) {
@@ -200,23 +345,23 @@ function open(options) {
200
345
  readyTimer = null;
201
346
  }
202
347
  const onMessage = (event) => {
203
- var _a;
348
+ var _a2;
204
349
  if (closed || loadTimedOut || terminalDelivered) return;
205
350
  if (event.origin !== hostedOrigin) return;
206
351
  if (!overlay.iframe.contentWindow || event.source !== overlay.iframe.contentWindow) {
207
352
  return;
208
353
  }
209
354
  const data = event.data;
210
- if (!data || typeof data !== "object" || data.protocol !== EMBED_PROTOCOL) {
355
+ if (!data || typeof data !== "object" || data.protocol !== names.protocol) {
211
356
  return;
212
357
  }
213
358
  stopHello();
214
359
  switch (data.type) {
215
- case "soliton:ready":
360
+ case names.ready:
216
361
  stopReadyWait();
217
362
  overlay.markReady();
218
363
  break;
219
- case "soliton:complete": {
364
+ case names.complete: {
220
365
  if (terminalDelivered) break;
221
366
  stopReadyWait();
222
367
  terminalDelivered = true;
@@ -226,14 +371,14 @@ function open(options) {
226
371
  });
227
372
  break;
228
373
  }
229
- case "soliton:error":
374
+ case names.error:
230
375
  stopReadyWait();
231
- (_a = options.onError) == null ? void 0 : _a.call(options, {
376
+ (_a2 = options.onError) == null ? void 0 : _a2.call(options, {
232
377
  code: typeof data.code === "string" ? data.code : "internal",
233
378
  message: typeof data.message === "string" ? data.message : ""
234
379
  });
235
380
  break;
236
- case "soliton:close":
381
+ case names.close:
237
382
  close();
238
383
  break;
239
384
  default:
@@ -242,11 +387,11 @@ function open(options) {
242
387
  };
243
388
  window.addEventListener("message", onMessage);
244
389
  readyTimer = setTimeout(() => {
245
- var _a;
390
+ var _a2;
246
391
  if (readyTimer === null || closed || terminalDelivered) return;
247
392
  loadTimedOut = true;
248
393
  try {
249
- (_a = options.onError) == null ? void 0 : _a.call(options, {
394
+ (_a2 = options.onError) == null ? void 0 : _a2.call(options, {
250
395
  code: "load_timeout",
251
396
  message: "Verification did not load. Please try again."
252
397
  });
@@ -255,7 +400,7 @@ function open(options) {
255
400
  }
256
401
  }, READY_TIMEOUT_MS);
257
402
  function close() {
258
- var _a;
403
+ var _a2;
259
404
  if (closed) return;
260
405
  closed = true;
261
406
  if (autoCloseTimer !== null) clearTimeout(autoCloseTimer);
@@ -263,10 +408,89 @@ function open(options) {
263
408
  stopHello();
264
409
  window.removeEventListener("message", onMessage);
265
410
  overlay.destroy();
266
- if (!terminalDelivered) (_a = options.onClose) == null ? void 0 : _a.call(options);
411
+ if (!terminalDelivered) (_a2 = options.onClose) == null ? void 0 : _a2.call(options);
267
412
  }
268
413
  return { close };
269
414
  }
415
+
416
+ // sdk/src/trustedOrigin.ts
417
+ function trustedOrigin(value) {
418
+ const url = new URL(value);
419
+ const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
420
+ if (url.origin !== value || url.username || url.password || value.includes("*") || url.protocol !== "https:" && !(url.protocol === "http:" && local)) {
421
+ throw new Error("Use an exact HTTPS origin (HTTP loopback is allowed for development)");
422
+ }
423
+ return url.origin;
424
+ }
425
+
426
+ // sdk/src/urlCheck.ts
427
+ var HOSTED_PATH_RE = /^\/v\/[0-9a-f]{32}$/;
428
+ function checkHostedUrl(raw, prefix, configuredOrigin, checkUnconfigured) {
429
+ let url;
430
+ try {
431
+ url = new URL(raw);
432
+ } catch (e) {
433
+ throw new Error(`${prefix} "url" is not a valid absolute URL`);
434
+ }
435
+ if (configuredOrigin !== void 0) {
436
+ if (url.origin !== configuredOrigin) {
437
+ throw new Error(`${prefix} "url" does not match the configured verificationOrigin`);
438
+ }
439
+ } else if (checkUnconfigured) {
440
+ checkUnconfigured(url);
441
+ } else {
442
+ throw new Error(`${prefix} open() requires "verificationOrigin"`);
443
+ }
444
+ if (url.username || url.password) {
445
+ throw new Error(`${prefix} "url" must not embed credentials`);
446
+ }
447
+ if (!HOSTED_PATH_RE.test(url.pathname)) {
448
+ throw new Error(
449
+ `${prefix} "url" does not look like a hosted verification URL (/v/{token})`
450
+ );
451
+ }
452
+ return { url, hostedOrigin: url.origin };
453
+ }
454
+
455
+ // sdk/src/hostedUrl.ts
456
+ var ERROR_PREFIX = "SolitonVerify:";
457
+ var ALLOWED_HTTPS_ORIGINS = /* @__PURE__ */ new Set([
458
+ "https://soliton.id",
459
+ "https://staging.soliton.id"
460
+ ]);
461
+ function parseHostedUrl(raw, verificationOrigin) {
462
+ const configuredOrigin = verificationOrigin === void 0 ? void 0 : trustedOrigin(verificationOrigin);
463
+ return checkHostedUrl(raw, ERROR_PREFIX, configuredOrigin, (url) => {
464
+ const isLocalHttp = url.protocol === "http:" && (url.hostname === "localhost" || url.hostname === "127.0.0.1");
465
+ if (!ALLOWED_HTTPS_ORIGINS.has(url.origin) && !isLocalHttp) {
466
+ throw new Error(
467
+ 'SolitonVerify: "url" must be hosted on https://soliton.id or https://staging.soliton.id (http is allowed for localhost/127.0.0.1 development only)'
468
+ );
469
+ }
470
+ });
471
+ }
472
+
473
+ // sdk/src/types.ts
474
+ var EMBED_PROTOCOL = "soliton-v1";
475
+
476
+ // sdk/src/index.ts
477
+ var SOLITON_NAMES = {
478
+ protocol: EMBED_PROTOCOL,
479
+ hello: "soliton:hello",
480
+ ready: "soliton:ready",
481
+ complete: "soliton:complete",
482
+ error: "soliton:error",
483
+ close: "soliton:close",
484
+ errorPrefix: "SolitonVerify:",
485
+ overlay: {
486
+ marker: "data-soliton-sdk",
487
+ animation: "soliton-sdk-spin",
488
+ title: "Soliton identity verification"
489
+ }
490
+ };
491
+ function open(options) {
492
+ return openOverlay(options, SOLITON_NAMES, parseHostedUrl);
493
+ }
270
494
  var SolitonVerify = { open };
271
495
  var index_default = SolitonVerify;
272
496
  export {
package/dist/overlay.d.ts CHANGED
@@ -7,11 +7,27 @@
7
7
  * styles so the SDK needs no stylesheet and cannot clash with host CSS
8
8
  * (spinner keyframes ride in a scoped <style> tag inside the overlay).
9
9
  */
10
+ /**
11
+ * Names the overlay puts in the host page's DOM. Each SDK entry injects its
12
+ * own, so an entry's bundle carries only the names it uses.
13
+ */
14
+ export interface OverlayNames {
15
+ /** Attribute marking the overlay's elements ("overlay", "loading"). */
16
+ marker: string;
17
+ /** Keyframes name of the loading spinner. */
18
+ animation: string;
19
+ /** Accessible title of the iframe. */
20
+ title: string;
21
+ }
10
22
  export interface Overlay {
11
23
  iframe: HTMLIFrameElement;
12
- /** Hide the loading state once the hosted page reports soliton:ready. */
24
+ /** Hide the loading state once the hosted page reports ready. */
13
25
  markReady(): void;
14
26
  /** Remove the overlay from the DOM and restore body scroll. Idempotent. */
15
27
  destroy(): void;
16
28
  }
17
- export declare function createOverlay(iframeSrc: string, onCloseClick: () => void): Overlay;
29
+ /**
30
+ * `backdrop` and `closeFill` are already validated opaque hex colors ("#rgb"
31
+ * / "#rrggbb") from the theme, or undefined for the defaults.
32
+ */
33
+ export declare function createOverlay(iframeSrc: string, onCloseClick: () => void, names: OverlayNames, backdrop?: string, closeFill?: string): Overlay;
@@ -0,0 +1,61 @@
1
+ /**
2
+ * Optional colors for the hosted verification screens: the public types, the
3
+ * pre-filter applied before a theme goes on the iframe URL as its `theme`
4
+ * query parameter, and the colors of the overlay's own backdrop and close
5
+ * button.
6
+ *
7
+ * The pre-filter applies the hosted page's own rules, so an integrator sees
8
+ * in the console what was ignored: known keys only, opaque "#rgb" or
9
+ * "#rrggbb" strings only, colorScheme in its enum. Everything else is dropped
10
+ * with one console.warn. Nothing here throws: a theme must never stop or
11
+ * delay a verification. The hosted page validates the parameter again, so
12
+ * this is a courtesy, not a security boundary.
13
+ *
14
+ * Shared by every SDK entry: keep it free of any entry's names.
15
+ */
16
+ /** Names of the colors a theme can set. */
17
+ export type ThemeColorKey = "background" | "surface" | "surfaceMuted" | "text" | "textMuted" | "border" | "primary" | "primaryPressed" | "onPrimary" | "accent" | "progress" | "success" | "warning" | "error" | "illustration" | "overlay" | "cameraBackground" | "oval" | "ovalProgress" | "closeButton";
18
+ /** Colors as opaque hex strings, "#rgb" or "#rrggbb". Unknown keys and other values are ignored. */
19
+ export type ThemeColors = Partial<Record<ThemeColorKey, string>>;
20
+ /**
21
+ * Colors for the hosted verification screens, the camera screen and the close
22
+ * button included. Only the light flashes during the check keep their own
23
+ * colors.
24
+ */
25
+ export interface VerificationTheme {
26
+ /** "auto" (the default) follows the device's light or dark setting. */
27
+ colorScheme?: "auto" | "light" | "dark";
28
+ /** Light palette. The camera screen always uses this one. */
29
+ colors?: ThemeColors;
30
+ /** Dark palette. */
31
+ darkColors?: ThemeColors;
32
+ }
33
+ /** The pre-filtered theme and its query parameter value; both null when nothing valid remains. */
34
+ export interface PreparedTheme {
35
+ theme: VerificationTheme | null;
36
+ param: string | null;
37
+ }
38
+ /** Longest `theme` parameter value the hosted page accepts. */
39
+ export declare const MAX_THEME_PARAM_LENGTH = 4096;
40
+ /**
41
+ * Pre-filter `source.theme` and serialize what remains. Never throws; warns
42
+ * once (prefixed with `warnPrefix`) when anything was ignored. An unset theme
43
+ * (undefined or null) is silently absent.
44
+ */
45
+ export declare function prepareTheme(source: {
46
+ theme?: unknown;
47
+ }, warnPrefix: string, maxLength?: number): PreparedTheme;
48
+ /**
49
+ * The palette active when open() runs: colorScheme "light" or "dark" forces
50
+ * one, "auto" (the default) follows the device. A light value is never
51
+ * carried into the dark scheme. Asks no media query without a theme.
52
+ */
53
+ export declare function activePalette(theme: VerificationTheme | null): ThemeColors | undefined;
54
+ /** The active palette's `overlay` color, or undefined when it sets none. */
55
+ export declare function overlayBackdrop(theme: VerificationTheme | null): string | undefined;
56
+ /** The active palette's `closeButton` color, or undefined when it sets none. */
57
+ export declare function closeButtonFill(theme: VerificationTheme | null): string | undefined;
58
+ /** WCAG relative luminance of an opaque "#rgb" or "#rrggbb" color. */
59
+ export declare function relativeLuminance(hex: string): number;
60
+ /** WCAG contrast ratio between two opaque hex colors (1 to 21). */
61
+ export declare function contrastRatio(a: string, b: string): number;
package/dist/types.d.ts CHANGED
@@ -11,6 +11,7 @@
11
11
  * are safe. Never rename a type, never remove or retype a field, and never
12
12
  * add payload fields the wrapper is required to understand.
13
13
  */
14
+ import type { VerificationTheme } from "./theme";
14
15
  export interface SolitonVerifyOptions {
15
16
  /**
16
17
  * Hosted URL from the v1 verification API or v2 session link API. Choose
@@ -37,8 +38,17 @@ export interface SolitonVerifyOptions {
37
38
  verificationId: string;
38
39
  }) => void;
39
40
  /** Flow-level errors: link_expired, link_invalid, origin_not_allowed,
40
- * storage_unavailable, link_unavailable, consent_required, internal,
41
- * load_timeout. consent_required means your account requires consent, you
41
+ * storage_unavailable, link_unavailable, link_already_used,
42
+ * consent_required, capture_failed, internal, load_timeout. link_already_used means the
43
+ * capture was already started from this link in another browser or device,
44
+ * or the check had already finished when this browser came back to it (a
45
+ * reload or a new tab in the same browser otherwise continues it): start a
46
+ * new session for the user. Using up the tries ends with onComplete, as
47
+ * after a final failed take. capture_failed means the capture could not be
48
+ * completed on this device (its last try never reached the server): there is
49
+ * no verdict, the check stays open and expires unfinished; start a new
50
+ * session for the user.
51
+ * consent_required means your account requires consent, you
42
52
  * skipped the instructions screen (intro=skip) and sent none, and the account
43
53
  * is set to refuse such checks. A load_timeout closes the overlay after this
44
54
  * callback and invokes onClose, never onComplete. */
@@ -50,6 +60,12 @@ export interface SolitonVerifyOptions {
50
60
  onClose?: () => void;
51
61
  /** Reserved; passed through to the hosted page as a query param. */
52
62
  locale?: string;
63
+ /**
64
+ * Optional colors for the hosted verification screens, the camera screen
65
+ * and the close button included. Only the light flashes during the check
66
+ * keep their own colors.
67
+ */
68
+ theme?: VerificationTheme;
53
69
  }
54
70
  export interface SolitonVerifyHandle {
55
71
  close(): void;
@@ -0,0 +1,23 @@
1
+ /**
2
+ * URL rules shared by every SDK entry point. The SDK only ever frames URLs
3
+ * shaped like the ones the verification APIs mint: an accepted origin and a
4
+ * bare /v/{32 hex} path. Everything else throws synchronously: a bad URL is
5
+ * an integration bug, not a runtime flow event, so it must fail loudly at the
6
+ * call site instead of rendering an attacker-chosen page in the overlay.
7
+ *
8
+ * Each entry supplies its own error prefix and, when it has one, its own rule
9
+ * for URLs opened without a configured origin, so no entry's bundle carries
10
+ * another entry's hosts or names.
11
+ */
12
+ export interface ParsedHostedUrl {
13
+ /** The validated URL, normalized by the URL parser. */
14
+ url: URL;
15
+ /** Origin the SDK will trust for postMessage events. */
16
+ hostedOrigin: string;
17
+ }
18
+ /**
19
+ * Validate `raw` against `configuredOrigin` (already checked by
20
+ * trustedOrigin) when there is one, else against `checkUnconfigured`. An entry
21
+ * without a rule for unconfigured URLs refuses them.
22
+ */
23
+ export declare function checkHostedUrl(raw: string, prefix: string, configuredOrigin: string | undefined, checkUnconfigured?: (url: URL) => void): ParsedHostedUrl;