@softure-ai/marketing-kit 0.1.8 → 0.1.10

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 (85) hide show
  1. package/CHANGELOG.md +42 -0
  2. package/README.md +111 -8
  3. package/dist/cli/main.js +42 -6
  4. package/dist/cli/main.js.map +1 -1
  5. package/dist/config/actions-schema.d.ts +7 -1
  6. package/dist/config/actions-schema.d.ts.map +1 -1
  7. package/dist/config/actions-schema.js +18 -3
  8. package/dist/config/actions-schema.js.map +1 -1
  9. package/dist/config/config.d.ts +2 -0
  10. package/dist/config/config.d.ts.map +1 -1
  11. package/dist/config/config.js +2 -1
  12. package/dist/config/config.js.map +1 -1
  13. package/dist/config/placeholders.d.ts +32 -0
  14. package/dist/config/placeholders.d.ts.map +1 -0
  15. package/dist/config/placeholders.js +41 -0
  16. package/dist/config/placeholders.js.map +1 -0
  17. package/dist/config/schema.d.ts +2214 -1
  18. package/dist/config/schema.d.ts.map +1 -1
  19. package/dist/config/schema.js +93 -4
  20. package/dist/config/schema.js.map +1 -1
  21. package/dist/config/shot-steps.d.ts +637 -0
  22. package/dist/config/shot-steps.d.ts.map +1 -0
  23. package/dist/config/shot-steps.js +44 -0
  24. package/dist/config/shot-steps.js.map +1 -0
  25. package/dist/film.d.ts +20 -5
  26. package/dist/film.d.ts.map +1 -1
  27. package/dist/film.js.map +1 -1
  28. package/dist/record/actions.d.ts +3 -10
  29. package/dist/record/actions.d.ts.map +1 -1
  30. package/dist/record/actions.js +13 -24
  31. package/dist/record/actions.js.map +1 -1
  32. package/dist/record/locator.d.ts +10 -0
  33. package/dist/record/locator.d.ts.map +1 -0
  34. package/dist/record/locator.js +24 -0
  35. package/dist/record/locator.js.map +1 -0
  36. package/dist/record/record.d.ts.map +1 -1
  37. package/dist/record/record.js +51 -17
  38. package/dist/record/record.js.map +1 -1
  39. package/dist/record/screen-guard.d.ts +13 -0
  40. package/dist/record/screen-guard.d.ts.map +1 -0
  41. package/dist/record/screen-guard.js +27 -0
  42. package/dist/record/screen-guard.js.map +1 -0
  43. package/dist/screenshot/gates.d.ts +46 -5
  44. package/dist/screenshot/gates.d.ts.map +1 -1
  45. package/dist/screenshot/gates.js +41 -5
  46. package/dist/screenshot/gates.js.map +1 -1
  47. package/dist/screenshot/prepare.d.ts +18 -0
  48. package/dist/screenshot/prepare.d.ts.map +1 -0
  49. package/dist/screenshot/prepare.js +60 -0
  50. package/dist/screenshot/prepare.js.map +1 -0
  51. package/dist/screenshot/screenshot.d.ts +9 -2
  52. package/dist/screenshot/screenshot.d.ts.map +1 -1
  53. package/dist/screenshot/screenshot.js +86 -7
  54. package/dist/screenshot/screenshot.js.map +1 -1
  55. package/dist/screenshot/shot-texts.d.ts +26 -0
  56. package/dist/screenshot/shot-texts.d.ts.map +1 -0
  57. package/dist/screenshot/shot-texts.js +55 -0
  58. package/dist/screenshot/shot-texts.js.map +1 -0
  59. package/dist/screenshot/sign-in.d.ts +34 -0
  60. package/dist/screenshot/sign-in.d.ts.map +1 -0
  61. package/dist/screenshot/sign-in.js +66 -0
  62. package/dist/screenshot/sign-in.js.map +1 -0
  63. package/dist/screenshot/steps.d.ts +12 -0
  64. package/dist/screenshot/steps.d.ts.map +1 -0
  65. package/dist/screenshot/steps.js +38 -0
  66. package/dist/screenshot/steps.js.map +1 -0
  67. package/package.json +3 -2
  68. package/schema/marketing.schema.json +1893 -18
  69. package/src/cli/main.ts +40 -6
  70. package/src/config/actions-schema.ts +18 -3
  71. package/src/config/config.ts +4 -1
  72. package/src/config/placeholders.ts +60 -0
  73. package/src/config/schema.ts +104 -5
  74. package/src/config/shot-steps.ts +58 -0
  75. package/src/film.ts +15 -5
  76. package/src/record/actions.ts +11 -32
  77. package/src/record/locator.ts +37 -0
  78. package/src/record/record.ts +53 -19
  79. package/src/record/screen-guard.ts +37 -0
  80. package/src/screenshot/gates.ts +60 -5
  81. package/src/screenshot/prepare.ts +64 -0
  82. package/src/screenshot/screenshot.ts +89 -8
  83. package/src/screenshot/shot-texts.ts +72 -0
  84. package/src/screenshot/sign-in.ts +91 -0
  85. package/src/screenshot/steps.ts +44 -0
@@ -0,0 +1,91 @@
1
+ import type { Browser, BrowserContext, Page } from "playwright";
2
+
3
+ import type { ShotStep } from "../config/shot-steps.js";
4
+ import { containsPhrase } from "../film.js";
5
+ import { findStatusFailure } from "./gates.js";
6
+ import type { ScreenshotBrowser } from "./screenshot.js";
7
+ import { runShotSteps } from "./steps.js";
8
+
9
+ /**
10
+ * `signIn` of marketing.json, done once per `shots` run: the sign-in page, its steps, then a phrase only a
11
+ * signed-in page shows. The session (cookies and localStorage) stays in memory and opens every `signedIn: true`
12
+ * screenshot; it is never written to disk. Values are resolved before they get here and never printed.
13
+ */
14
+
15
+ /** The sign-in with its placeholders resolved. */
16
+ export interface SignInPlan {
17
+ path: string;
18
+ steps: ShotStep[];
19
+ expect: string;
20
+ }
21
+
22
+ export type SessionState = Awaited<ReturnType<BrowserContext["storageState"]>>;
23
+
24
+ export type SignInResult = { ok: true; session: SessionState } | { ok: false; message: string };
25
+
26
+ const NAVIGATION_TIMEOUT_MS = 30_000;
27
+ /** The submit usually navigates and the next page loads its data: more time than a screenshot's 5 s. */
28
+ export const SIGN_IN_PHRASE_TIMEOUT_MS = 15_000;
29
+ const PHRASE_POLL_MS = 250;
30
+
31
+ function describeError(error: unknown): string {
32
+ return error instanceof Error ? (error.message.split("\n")[0] ?? error.name) : String(error);
33
+ }
34
+
35
+ /** The page's visible text, or null while a navigation replaces the document (its context is destroyed). */
36
+ export async function readPageText(page: Page): Promise<string | null> {
37
+ try {
38
+ return await page.locator("body").innerText({ timeout: PHRASE_POLL_MS * 4 });
39
+ } catch {
40
+ // A navigation in flight or a body not there yet: the next poll reads the new page.
41
+ return null;
42
+ }
43
+ }
44
+
45
+ async function waitForSignedIn(page: Page, phrase: string): Promise<boolean> {
46
+ const deadline = Date.now() + SIGN_IN_PHRASE_TIMEOUT_MS;
47
+ for (;;) {
48
+ const text = await readPageText(page);
49
+ if (text !== null && containsPhrase(text, phrase)) return true;
50
+ if (Date.now() >= deadline) return false;
51
+ await page.waitForTimeout(PHRASE_POLL_MS);
52
+ }
53
+ }
54
+
55
+ export interface SignInOptions {
56
+ browser: Browser;
57
+ baseUrl: string;
58
+ settings: ScreenshotBrowser;
59
+ plan: SignInPlan;
60
+ }
61
+
62
+ export async function signIn(options: SignInOptions): Promise<SignInResult> {
63
+ const { browser, baseUrl, settings, plan } = options;
64
+ const url = new URL(plan.path, baseUrl).href;
65
+ const context = await browser.newContext({ colorScheme: settings.colorScheme, locale: settings.locale, timezoneId: settings.timezone });
66
+ try {
67
+ const page = await context.newPage();
68
+ let status: number | null;
69
+ try {
70
+ const response = await page.goto(url, { waitUntil: "load", timeout: NAVIGATION_TIMEOUT_MS });
71
+ status = response?.status() ?? null;
72
+ } catch (error) {
73
+ // Any navigation failure (refused connection, DNS, timeout) is the app's, not a bug of ours.
74
+ return { ok: false, message: `loading the sign-in page ${url}: ${describeError(error)}` };
75
+ }
76
+ const statusFailure = findStatusFailure(status, url);
77
+ if (statusFailure !== null) return { ok: false, message: `the sign-in page: ${statusFailure}` };
78
+ const stepFailure = await runShotSteps(page, plan.steps, "signIn.steps");
79
+ if (stepFailure !== null) return { ok: false, message: stepFailure };
80
+ if (!(await waitForSignedIn(page, plan.expect))) {
81
+ return { ok: false, message: `after the sign-in steps, ${new URL(page.url()).pathname} does not show "${plan.expect}" within ${SIGN_IN_PHRASE_TIMEOUT_MS / 1000} s` };
82
+ }
83
+ const session = await context.storageState();
84
+ if (session.cookies.length === 0 && session.origins.length === 0) {
85
+ return { ok: false, message: `the page shows "${plan.expect}", but the browser holds no session (no cookie, no localStorage); pick a phrase only a signed-in page shows` };
86
+ }
87
+ return { ok: true, session };
88
+ } finally {
89
+ await context.close();
90
+ }
91
+ }
@@ -0,0 +1,44 @@
1
+ import type { Page } from "playwright";
2
+
3
+ import type { ShotStep } from "../config/shot-steps.js";
4
+ import { getLocator } from "../record/locator.js";
5
+
6
+ /**
7
+ * Steps of the sign-in and of a screenshot entry, done in order on the page. A step that cannot be done (its
8
+ * element never appears, matches several, is not an input) is the page's or the config's fault, so it comes back as
9
+ * a message naming the step; the message never carries a `fill` value, which may be a password.
10
+ */
11
+
12
+ /** Long enough for a client-side page to render the element, short enough that a typo does not hang the run. */
13
+ export const STEP_TIMEOUT_MS = 10_000;
14
+
15
+ function describeError(error: unknown): string {
16
+ return error instanceof Error ? (error.message.split("\n")[0] ?? error.name) : String(error);
17
+ }
18
+
19
+ async function runStep(page: Page, step: ShotStep): Promise<void> {
20
+ const timeout = STEP_TIMEOUT_MS;
21
+ switch (step.do) {
22
+ case "fill":
23
+ return getLocator(page, step.target).fill(step.value, { timeout });
24
+ case "click":
25
+ return getLocator(page, step.target).click({ timeout });
26
+ case "check":
27
+ return getLocator(page, step.target).check({ timeout });
28
+ case "press":
29
+ return page.keyboard.press(step.key);
30
+ }
31
+ }
32
+
33
+ /** Null when every step was done; otherwise which one failed (`<where>[<index>] (<do>)`) and why. */
34
+ export async function runShotSteps(page: Page, steps: readonly ShotStep[], where: string): Promise<string | null> {
35
+ for (const [index, step] of steps.entries()) {
36
+ try {
37
+ await runStep(page, step);
38
+ } catch (error) {
39
+ // Every Playwright failure of a step (timeout, strict mode, not an input) is the page's or the config's.
40
+ return `${where}[${index}] (${step.do}): ${describeError(error)}`;
41
+ }
42
+ }
43
+ return null;
44
+ }