@parag.more.withsurface.com/forms-sdk 0.1.5 → 0.1.7

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 (107) hide show
  1. package/README.md +12 -6
  2. package/dist/index.cjs +1 -2736
  3. package/dist/index.mjs +1 -2713
  4. package/dist/react/index.cjs +1 -43
  5. package/dist/react/index.mjs +1 -20
  6. package/dist/surface-forms-sdk.min.js +1 -1
  7. package/dist/types/bind/bindForm.d.ts +2 -0
  8. package/dist/types/bind/bookingWidget.d.ts +29 -6
  9. package/dist/types/bind/scheduler/embedUtils.d.ts +51 -0
  10. package/dist/types/bind/scheduler/mountScheduler.d.ts +2 -0
  11. package/dist/types/bind/scheduler/providers/cal.d.ts +3 -0
  12. package/dist/types/bind/scheduler/providers/calendly.d.ts +3 -0
  13. package/dist/types/bind/scheduler/providers/chilical.d.ts +3 -0
  14. package/dist/types/bind/scheduler/providers/clari.d.ts +3 -0
  15. package/dist/types/bind/scheduler/providers/hubspot.d.ts +3 -0
  16. package/dist/types/bind/scheduler/providers/index.d.ts +4 -0
  17. package/dist/types/bind/scheduler/providers/reclaimai.d.ts +3 -0
  18. package/dist/types/bind/scheduler/providers/revenuehero.d.ts +3 -0
  19. package/dist/types/bind/scheduler/providers/savvycal.d.ts +3 -0
  20. package/dist/types/bind/scheduler/providers/surface.d.ts +3 -0
  21. package/dist/types/bind/scheduler/providers/zoom.d.ts +3 -0
  22. package/dist/types/bind/scheduler/styles.d.ts +3 -0
  23. package/dist/types/bind/scheduler/types.d.ts +65 -0
  24. package/dist/types/core/client/emailValidation.d.ts +3 -0
  25. package/dist/types/core/client/responses.d.ts +3 -0
  26. package/dist/types/core/client/runtimeConfig.d.ts +40 -0
  27. package/dist/types/core/client/scheduler.d.ts +4 -0
  28. package/dist/types/core/client/transport.d.ts +4 -0
  29. package/dist/types/core/engine/answerAudit.d.ts +3 -0
  30. package/dist/types/core/engine/answerStates.d.ts +4 -0
  31. package/dist/types/core/engine/formEngine.d.ts +18 -0
  32. package/dist/types/core/engine/redirect.d.ts +1 -0
  33. package/dist/types/core/engine/responsePayload.d.ts +4 -0
  34. package/dist/types/core/engine/schedulerEvents.d.ts +40 -0
  35. package/dist/types/core/engine/urlData.d.ts +2 -0
  36. package/dist/types/core/engine/urlPrefill.d.ts +1 -0
  37. package/dist/types/core/events/dropoffDetection.d.ts +1 -0
  38. package/dist/types/core/events/emitter.d.ts +1 -0
  39. package/dist/types/core/events/formJourneyTracker.d.ts +1 -0
  40. package/dist/types/core/events/pushEvents.d.ts +2 -0
  41. package/dist/types/core/events/startedDetection.d.ts +1 -0
  42. package/dist/types/core/events/viewDetection.d.ts +1 -0
  43. package/dist/types/core/identity/browserFingerprint.d.ts +3 -0
  44. package/dist/types/core/identity/ensureIdentified.d.ts +1 -0
  45. package/dist/types/core/identity/identify.d.ts +1 -0
  46. package/dist/types/core/identity/journey.d.ts +3 -0
  47. package/dist/types/core/identity/leadDataCache.d.ts +1 -0
  48. package/dist/types/enrichment/attachEnrichment.d.ts +1 -0
  49. package/dist/types/index.d.ts +5 -2
  50. package/dist/types/react/useSurfaceForm.d.ts +1 -0
  51. package/dist/types/surfaceForms.d.ts +28 -1
  52. package/dist/types/tracking/attachTracking.d.ts +1 -0
  53. package/dist/types/tracking/conversionRules.d.ts +3 -0
  54. package/dist/types/tracking/vendors.d.ts +3 -0
  55. package/docs/api.md +59 -43
  56. package/docs/reference/binding.md +86 -13
  57. package/docs/reference/clients.md +21 -1
  58. package/docs/reference/engine.md +14 -7
  59. package/docs/reference/events.md +4 -1
  60. package/llms.txt +95 -29
  61. package/package.json +1 -1
  62. package/skills/surface-forms-sdk/SKILL.md +66 -26
  63. package/skills/surface-forms-sdk/debugging.md +21 -19
  64. package/skills/surface-forms-sdk/patterns.md +71 -5
  65. package/dist/types/bind/bindForm.test.d.ts +0 -1
  66. package/dist/types/bind/bookingWidget.test.d.ts +0 -1
  67. package/dist/types/core/client/emailValidation.test.d.ts +0 -1
  68. package/dist/types/core/client/responses.test.d.ts +0 -1
  69. package/dist/types/core/client/runtimeConfig.contract.test.d.ts +0 -1
  70. package/dist/types/core/client/runtimeConfig.test.d.ts +0 -1
  71. package/dist/types/core/client/scheduler.contract.test.d.ts +0 -1
  72. package/dist/types/core/client/scheduler.test.d.ts +0 -1
  73. package/dist/types/core/client/transport.test.d.ts +0 -1
  74. package/dist/types/core/engine/answerAudit.test.d.ts +0 -1
  75. package/dist/types/core/engine/answerStates.contract.test.d.ts +0 -1
  76. package/dist/types/core/engine/formEngine.test.d.ts +0 -1
  77. package/dist/types/core/engine/redirect.test.d.ts +0 -1
  78. package/dist/types/core/engine/responsePayload.contract.test.d.ts +0 -1
  79. package/dist/types/core/engine/responsePayload.test.d.ts +0 -1
  80. package/dist/types/core/engine/urlData.contract.test.d.ts +0 -1
  81. package/dist/types/core/engine/urlData.test.d.ts +0 -1
  82. package/dist/types/core/engine/urlPrefill.test.d.ts +0 -1
  83. package/dist/types/core/events/dropoffDetection.test.d.ts +0 -1
  84. package/dist/types/core/events/emitter.test.d.ts +0 -1
  85. package/dist/types/core/events/formJourneyTracker.contract.test.d.ts +0 -1
  86. package/dist/types/core/events/formJourneyTracker.test.d.ts +0 -1
  87. package/dist/types/core/events/pushEvents.contract.test.d.ts +0 -1
  88. package/dist/types/core/events/pushEvents.test.d.ts +0 -1
  89. package/dist/types/core/events/startedDetection.test.d.ts +0 -1
  90. package/dist/types/core/events/viewDetection.test.d.ts +0 -1
  91. package/dist/types/core/identity/browserFingerprint.test.d.ts +0 -1
  92. package/dist/types/core/identity/ensureIdentified.test.d.ts +0 -1
  93. package/dist/types/core/identity/identify.contract.test.d.ts +0 -1
  94. package/dist/types/core/identity/identify.test.d.ts +0 -1
  95. package/dist/types/core/identity/journey.contract.test.d.ts +0 -1
  96. package/dist/types/core/identity/journey.test.d.ts +0 -1
  97. package/dist/types/core/identity/journey.testStubs.d.ts +0 -3
  98. package/dist/types/core/identity/leadDataCache.test.d.ts +0 -1
  99. package/dist/types/enrichment/attachEnrichment.test.d.ts +0 -1
  100. package/dist/types/react/ssr.test.d.ts +0 -1
  101. package/dist/types/react/useSurfaceForm.test.d.ts +0 -1
  102. package/dist/types/surfaceForms.test.d.ts +0 -1
  103. package/dist/types/tracking/attachTracking.test.d.ts +0 -1
  104. package/dist/types/tracking/conversionRules.contract.test.d.ts +0 -1
  105. package/dist/types/tracking/conversionRules.test.d.ts +0 -1
  106. package/dist/types/tracking/vendors.test.d.ts +0 -1
  107. package/dist/types/validation/attachEmailValidation.test.d.ts +0 -1
@@ -1,10 +1,12 @@
1
1
  import type { Transport } from "./transport";
2
2
  export type EmailValidationResult = {
3
3
  email: string;
4
+
4
5
  isValid: boolean;
5
6
  status?: string;
6
7
  reason?: string;
7
8
  blacklistEntryIds?: string[];
9
+
8
10
  failed?: boolean;
9
11
  };
10
12
  export type EmailValidator = {
@@ -14,6 +16,7 @@ export type EmailValidator = {
14
16
  export type CreateEmailValidatorOptions = {
15
17
  transport: Transport;
16
18
  environmentId: string;
19
+
17
20
  preview?: boolean;
18
21
  };
19
22
  export declare const createEmailValidator: ({ transport, environmentId, preview, }: CreateEmailValidatorOptions) => EmailValidator;
@@ -3,15 +3,18 @@ import type { Transport, TransportResult } from "./transport";
3
3
  export type CreateResponseResult = {
4
4
  responseId: string;
5
5
  leadId: string | null;
6
+
6
7
  resumeToken: string | null;
7
8
  };
8
9
  export declare const submitResponse: (transport: Transport, payload: FormResponsePayload) => Promise<TransportResult<CreateResponseResult>>;
9
10
  export declare const updateResponse: (transport: Transport, payload: FormUpdateResponsePayload) => void;
11
+
10
12
  export declare const updateResponseConfirmed: (transport: Transport, payload: FormUpdateResponsePayload) => Promise<TransportResult<unknown>>;
11
13
  export type StoredAnswerRow = {
12
14
  questionId: string;
13
15
  response: Record<string, unknown>;
14
16
  };
17
+
15
18
  export declare const fetchStoredResponse: (transport: Transport, { responseId, resumeToken }: {
16
19
  responseId: string;
17
20
  resumeToken: string;
@@ -1,4 +1,5 @@
1
1
  import type { Transport, TransportResult } from "./transport";
2
+
2
3
  type RuntimeStep = {
3
4
  id: string;
4
5
  endStepKind?: "thank_you" | "disqualified";
@@ -16,12 +17,14 @@ export type RuntimeConfig = {
16
17
  trackCookie?: boolean;
17
18
  } & Record<string, unknown>) | null;
18
19
  };
20
+
19
21
  export declare const fetchRuntimeConfig: (transport: Transport, formId: string, { preview, previewToken }?: {
20
22
  preview?: boolean;
21
23
  previewToken?: string;
22
24
  }) => Promise<TransportResult<{
23
25
  data?: RuntimeConfig;
24
26
  }>>;
27
+
25
28
  export declare const stepsOf: (config: RuntimeConfig["config"]) => Array<{
26
29
  id: string;
27
30
  endStepKind?: "thank_you" | "disqualified";
@@ -31,10 +34,47 @@ export declare const statefulQuestionsOf: (config: RuntimeConfig["config"]) => A
31
34
  componentType?: string;
32
35
  }>;
33
36
  export declare const statefulQuestionIdsOf: (config: RuntimeConfig["config"]) => string[];
37
+
34
38
  export declare const enrichmentSourcesOf: (config: RuntimeConfig["config"]) => Array<{
35
39
  questionId: string;
36
40
  fieldNames: string[];
37
41
  }>;
42
+
43
+ export type SchedulerStateRef = {
44
+ stepId: string;
45
+ questionId: string;
46
+ };
47
+
48
+ export type SchedulerParamRef = SchedulerStateRef & {
49
+ variable: string;
50
+ };
51
+ export type SchedulerQuestion = {
52
+ questionId: string;
53
+ stepId: string;
54
+
55
+ componentType: "CalendlyScreen" | "DynamicScheduler";
56
+
57
+ calendarType: string;
58
+ content: {
59
+ dataUrl?: string;
60
+ eventTypeId?: string;
61
+ savvyCalLinkId?: string;
62
+ revenueHeroRouterId?: string;
63
+ dataUrlParams?: Record<string, SchedulerParamRef>;
64
+ linkNameToStep?: SchedulerStateRef;
65
+ linkLastNameToStep?: SchedulerStateRef;
66
+ linkEmailToStep?: SchedulerStateRef;
67
+ addSchedulerQueryParams?: boolean;
68
+ skipFormIfPrefilled?: boolean;
69
+
70
+ calendars?: unknown[];
71
+ defaultCalendar?: unknown;
72
+ };
73
+ };
74
+
75
+ export declare const schedulerQuestionsOf: (config: RuntimeConfig["config"]) => SchedulerQuestion[];
76
+
38
77
  export declare const hasDeclaredEnrichmentSource: (config: RuntimeConfig["config"]) => boolean;
78
+
39
79
  export declare const hasEnabledEnrichmentProvider: (settings: RuntimeConfig["settings"]) => boolean;
40
80
  export {};
@@ -1,4 +1,5 @@
1
1
  import type { Transport, TransportResult } from "./transport";
2
+
2
3
  export type BookingAttendee = {
3
4
  name: string;
4
5
  email: string;
@@ -44,6 +45,7 @@ export type SchedulerClient = {
44
45
  }>>;
45
46
  getMonthAvailability: (args: {
46
47
  eventTypeId: string;
48
+
47
49
  month: string;
48
50
  timezone: string;
49
51
  duration?: number;
@@ -66,6 +68,7 @@ export type SchedulerClient = {
66
68
  book: (args: {
67
69
  eventTypeId: string;
68
70
  startTime: string;
71
+
69
72
  endTime: string;
70
73
  timezone: string;
71
74
  inviteeName: string;
@@ -90,5 +93,6 @@ export declare const createSchedulerClient: ({ transport, preview, }: {
90
93
  transport: Transport;
91
94
  preview?: boolean;
92
95
  }) => SchedulerClient;
96
+
93
97
  export declare const toSchedulerAnswerState: (booking: Booking) => Record<string, unknown>;
94
98
  export {};
@@ -1,4 +1,7 @@
1
+
2
+
1
3
  export declare const DEFAULT_API_BASE_URL = "https://forms.withsurface.com";
4
+
2
5
  export declare const SDK_VERSION = "0.1.0";
3
6
  export type TransportResult<TData> = {
4
7
  ok: true;
@@ -21,6 +24,7 @@ export type Transport = {
21
24
  keepalive?: boolean;
22
25
  credentials?: boolean;
23
26
  }) => Promise<TransportResult<TData>>;
27
+
24
28
  beacon: (path: string, payload: unknown) => boolean;
25
29
  };
26
30
  export declare const createTransport: ({ apiBaseUrl, }?: {
@@ -1,9 +1,12 @@
1
+
1
2
  export type AuditedQuestion = {
2
3
  questionId: string;
3
4
  componentType?: string;
4
5
  };
5
6
  export declare const auditAnswer: ({ questions, questionId, merged, }: {
7
+
6
8
  questions: Map<string, AuditedQuestion>;
7
9
  questionId: string;
10
+
8
11
  merged: Record<string, unknown>;
9
12
  }) => void;
@@ -1,3 +1,4 @@
1
+
1
2
  export type ShortInputAnswer = {
2
3
  type: "ShortInput";
3
4
  input: string;
@@ -23,6 +24,7 @@ export type FileUploaderAnswer = {
23
24
  type: "FileUploader";
24
25
  fileUrl?: string;
25
26
  };
27
+
26
28
  export type MultipleOptionsAnswer = {
27
29
  type: "MultipleOptionsQuestion";
28
30
  choices: Array<{
@@ -56,11 +58,13 @@ export type MultipleChoiceSingleAnswerAnswer = {
56
58
  value: string;
57
59
  index: number;
58
60
  };
61
+
59
62
  export declare const IDENTITY_INFO_ANSWER_KEYS: readonly ["firstName", "lastName", "fullName", "emailAddress", "workEmailAddress", "phoneNumber", "companyName", "numberOfEmployees", "websiteUrl", "title", "streetAddress", "aptSuiteEtc", "city", "state", "country", "zipCode", "companyRevenue", "profilePictureUrl"];
60
63
  export type IdentityInfoAnswerKey = (typeof IDENTITY_INFO_ANSWER_KEYS)[number];
61
64
  export type IdentityInfoAnswer = {
62
65
  type: "IdentityInfo";
63
66
  } & Partial<Record<IdentityInfoAnswerKey, string>>;
67
+
64
68
  export type SchedulerAnswer = {
65
69
  type: "CalendlyScreen" | "DynamicScheduler";
66
70
  eventScheduled: boolean;
@@ -3,6 +3,8 @@ import { type Unsubscribe } from "../events/emitter";
3
3
  import type { FormJourneyTracker, FormJourneyTransitionReason } from "../events/formJourneyTracker";
4
4
  import { type PushEventClient } from "../events/pushEvents";
5
5
  import { type AnswerStates, type ExternalStates } from "./responsePayload";
6
+ import type { SchedulerLifecycleEvent } from "./schedulerEvents";
7
+
6
8
  export type ResolvedNextStep = {
7
9
  stepId: string;
8
10
  reason?: FormJourneyTransitionReason;
@@ -37,27 +39,39 @@ export type FormEngineEvents = {
37
39
  scope: "submit";
38
40
  error: unknown;
39
41
  };
42
+ scheduler: SchedulerLifecycleEvent;
40
43
  };
41
44
  export type FormEngineState = {
42
45
  currentStepId: string;
43
46
  answers: AnswerStates;
47
+
44
48
  externalStates: ExternalStates;
45
49
  responseId: string | null;
50
+
46
51
  resumeToken: string | null;
47
52
  finished: boolean;
48
53
  };
49
54
  export type FormEngine = {
50
55
  setAnswer: (questionId: string, state: Record<string, unknown>) => void;
56
+
51
57
  setExternalState: (id: string, state: {
52
58
  type: string;
53
59
  } & Record<string, unknown>) => void;
60
+
54
61
  mergeMeta: (partial: Record<string, unknown>) => void;
62
+
55
63
  next: () => Promise<void>;
56
64
  back: () => void;
65
+
57
66
  goToStep: (stepId: string) => Promise<void>;
67
+
58
68
  submit: () => Promise<void>;
69
+
59
70
  disqualify: () => Promise<void>;
60
71
  savePartial: () => Promise<void>;
72
+
73
+ notifyScheduler: (event: SchedulerLifecycleEvent) => void;
74
+
61
75
  flush: () => Promise<void>;
62
76
  markViewed: () => void;
63
77
  on: <K extends keyof FormEngineEvents>(event: K, handler: (payload: FormEngineEvents[K]) => void) => Unsubscribe;
@@ -67,6 +81,7 @@ export type FormEngine = {
67
81
  export declare const createFormEngine: ({ formId, environmentId, steps, transport, resolveNextStep, trackPartialResponses, trackCookies, externalStates, meta, identity, pushEvents, formJourney, preview, resume, }: {
68
82
  formId: string;
69
83
  environmentId?: string;
84
+
70
85
  steps: Array<{
71
86
  id: string;
72
87
  endStepKind?: "thank_you" | "disqualified";
@@ -77,6 +92,7 @@ export declare const createFormEngine: ({ formId, environmentId, steps, transpor
77
92
  trackCookies?: boolean;
78
93
  externalStates?: ExternalStates;
79
94
  meta?: Record<string, unknown>;
95
+
80
96
  identity?: () => {
81
97
  fingerprint?: string;
82
98
  leadSessionId?: string;
@@ -84,7 +100,9 @@ export declare const createFormEngine: ({ formId, environmentId, steps, transpor
84
100
  };
85
101
  pushEvents?: PushEventClient;
86
102
  formJourney?: FormJourneyTracker;
103
+
87
104
  preview?: boolean;
105
+
88
106
  resume?: {
89
107
  responseId: string;
90
108
  answers?: Record<string, Record<string, unknown>>;
@@ -1,3 +1,4 @@
1
+
1
2
  export type RedirectType = "NewTab" | "CurrentWindow";
2
3
  export declare const DEFAULT_REDIRECT_TIMEOUT_MS = 400;
3
4
  export declare const buildRedirectUrl: (url: string, { leadId, sessionId }?: {
@@ -1,8 +1,11 @@
1
+
1
2
  export type SingleFormResponse = {
2
3
  questionId: string;
3
4
  response: Record<string, unknown>;
4
5
  };
6
+
5
7
  export type AnswerStates = Record<string, Record<string, Record<string, unknown>>>;
8
+
6
9
  export type ExternalStates = Record<string, {
7
10
  type: string;
8
11
  } & Record<string, unknown>>;
@@ -35,6 +38,7 @@ type BuildPayloadOptions = {
35
38
  invalidResponse: boolean;
36
39
  trackCookies: boolean;
37
40
  meta?: Record<string, unknown>;
41
+
38
42
  personAttributeEnrichedFields?: Record<string, unknown>;
39
43
  fingerprint?: string;
40
44
  leadSessionId?: string;
@@ -0,0 +1,40 @@
1
+
2
+
3
+ export type SchedulerProvider = "Surface" | "Calendly" | "Hubspot" | "Cal" | "SavvyCal" | "RevenueHero" | "ReclaimAI" | "Clari" | "ChiliCal" | "Zoom";
4
+ export type SchedulerBookingSummary = {
5
+ provider: SchedulerProvider;
6
+
7
+ uri: string;
8
+ meetingTime?: string;
9
+ meetingEndTime?: string;
10
+ inviteeName?: string;
11
+ guestEmails?: string;
12
+ ownerEmails?: string;
13
+ joinLink?: string;
14
+
15
+ raw?: unknown;
16
+ };
17
+ export type SchedulerLifecycleEvent = {
18
+ questionId: string;
19
+ stepId: string;
20
+ provider: SchedulerProvider;
21
+ } & ({
22
+ type: "viewed";
23
+ } | {
24
+ type: "date_selected";
25
+ date?: string;
26
+ } | {
27
+ type: "slot_selected";
28
+ slot?: {
29
+ start: string;
30
+ end?: string;
31
+ };
32
+ } | {
33
+ type: "form_opened";
34
+ } | {
35
+ type: "booking_confirmed";
36
+ booking: SchedulerBookingSummary;
37
+ } | {
38
+ type: "booking_cancelled";
39
+ reason?: string;
40
+ });
@@ -1,3 +1,4 @@
1
+
1
2
  export type UrlData = {
2
3
  type: "URL_DATA";
3
4
  fullUrl?: string;
@@ -8,6 +9,7 @@ export type UrlData = {
8
9
  export declare const constructUrlParamsObject: (url: string) => Record<string, string>;
9
10
  export declare const parseCookiesObject: (cookieString: string) => Record<string, string>;
10
11
  export declare const buildUrlData: ({ defaultUrl, trackCookies, }?: {
12
+
11
13
  defaultUrl?: string;
12
14
  trackCookies?: boolean;
13
15
  }) => UrlData;
@@ -1,3 +1,4 @@
1
+
1
2
  export type ParsedUrlQuestionId = {
2
3
  originalId: string;
3
4
  questionId: string;
@@ -1,4 +1,5 @@
1
1
  import type { PushEventClient } from "./pushEvents";
2
+
2
3
  export declare const observeDropoff: (pushEventClient: PushEventClient, getState: () => {
3
4
  started: boolean;
4
5
  formId: string;
@@ -1,3 +1,4 @@
1
+
1
2
  export type Unsubscribe = () => void;
2
3
  export type Emitter<TEventMap extends Record<string, unknown>> = {
3
4
  on: <K extends keyof TEventMap>(event: K, handler: (payload: TEventMap[K]) => void) => Unsubscribe;
@@ -1,4 +1,5 @@
1
1
  import type { Transport } from "../client/transport";
2
+
2
3
  export type FormJourneyOutcome = "in_progress" | "completed" | "partial" | "disqualified" | "dropped_off";
3
4
  export type FormJourneyTransitionReason = "initial" | "linear" | "conditional_match" | "default_fallback" | "prefill_jump" | "back_nav" | "auto_skip";
4
5
  export type FormJourneyVisit = {
@@ -1,4 +1,5 @@
1
1
  import type { Transport } from "../client/transport";
2
+
2
3
  export type SurfaceEventType = "form_viewed" | "form_started" | "form_completed" | "form_step_viewed" | "form_step_submitted" | "form_step_dropoff" | "form_question_submitted" | "response_submission_created" | "response_submission_error" | "script_initiated";
3
4
  export type SurfaceEventEntityType = "form" | "form_step" | "response";
4
5
  export type PushEventProperty = {
@@ -15,6 +16,7 @@ export type PushEventPayload = {
15
16
  leadId?: string;
16
17
  environmentId?: string;
17
18
  };
19
+
18
20
  export type PushEventBatch = {
19
21
  events: [
20
22
  PushEventPayload & {
@@ -1 +1,2 @@
1
+
1
2
  export declare const createStartedDetector: <T>(initial: T) => ((current: T) => boolean);
@@ -1 +1,2 @@
1
+
1
2
  export declare const observeFormView: (element: Element, onViewed: () => void) => (() => void);
@@ -1,3 +1,4 @@
1
+
1
2
  export type Fingerprint = {
2
3
  deviceType: "Mobile" | "Desktop";
3
4
  screen: {
@@ -12,9 +13,11 @@ export type Fingerprint = {
12
13
  }>;
13
14
  os: string;
14
15
  language: string;
16
+
15
17
  plugins?: string[];
16
18
  timezone: string;
17
19
  environmentId: string;
20
+
18
21
  id: string;
19
22
  };
20
23
  export declare function getHash(input: string): Promise<string>;
@@ -1,6 +1,7 @@
1
1
  import type { Transport } from "../client/transport";
2
2
  import { type LeadSource } from "./identify";
3
3
  import { type CachedLeadData } from "./leadDataCache";
4
+
4
5
  export declare const ensureIdentified: ({ transport, environmentId, formId, pageUrl, source, preview, }: {
5
6
  transport: Transport;
6
7
  environmentId: string;
@@ -1,4 +1,5 @@
1
1
  import type { Transport } from "../client/transport";
2
+
2
3
  export type LeadSource = "surfaceForm" | "htmlForm" | "websiteDeAnon" | "webhook" | "website" | "imported" | "scheduler" | "linkedin" | "sdkForm";
3
4
  export type IdentifyPayload = {
4
5
  environmentId: string;
@@ -1,9 +1,12 @@
1
1
  import type { Transport } from "../client/transport";
2
+
2
3
  export declare const JOURNEY_COOKIE_NAME = "surface_journey_id";
3
4
  export declare const RECENT_VISIT_COOKIE_NAME = "surface_recent_visit";
4
5
  export type JourneyTracker = {
5
6
  trackPageView: (url?: string) => Promise<void>;
7
+
6
8
  observeRouteChanges: () => () => void;
9
+
7
10
  clear: () => void;
8
11
  };
9
12
  export declare const createJourneyTracker: ({ transport, environmentId, }: {
@@ -1,3 +1,4 @@
1
+
1
2
  export declare const LEAD_DATA_STORAGE_KEY = "surfaceLeadData";
2
3
  export declare const LEAD_DATA_TTL_MS: number;
3
4
  export type CachedLeadData = {
@@ -1,5 +1,6 @@
1
1
  import type { Transport } from "../core/client/transport";
2
2
  import type { FormEngine } from "../core/engine/formEngine";
3
+
3
4
  export type EnrichmentSource = {
4
5
  questionId: string;
5
6
  fieldNames: string[];
@@ -1,14 +1,17 @@
1
1
  export { bindForm, type BindFormOptions } from "./bind/bindForm";
2
- export { mountBookingWidget, type BookingWidgetOptions } from "./bind/bookingWidget";
2
+ export { mountBookingWidget, type BookingIdentity, type BookingWidgetEvent, type BookingWidgetOptions, } from "./bind/bookingWidget";
3
+ export { mountScheduler } from "./bind/scheduler/mountScheduler";
4
+ export { type MountSchedulerOptions } from "./bind/scheduler/types";
3
5
  export { createEmailValidator, type CreateEmailValidatorOptions, type EmailValidationResult, type EmailValidator, } from "./core/client/emailValidation";
4
6
  export { submitResponse, updateResponse, type CreateResponseResult } from "./core/client/responses";
5
- export { enrichmentSourcesOf, fetchRuntimeConfig, hasEnabledEnrichmentProvider, statefulQuestionIdsOf, statefulQuestionsOf, stepsOf, type RuntimeConfig, } from "./core/client/runtimeConfig";
7
+ export { enrichmentSourcesOf, fetchRuntimeConfig, hasEnabledEnrichmentProvider, schedulerQuestionsOf, statefulQuestionIdsOf, statefulQuestionsOf, stepsOf, type RuntimeConfig, type SchedulerParamRef, type SchedulerQuestion, type SchedulerStateRef, } from "./core/client/runtimeConfig";
6
8
  export { createSchedulerClient, toSchedulerAnswerState, type AvailabilitySummary, type Booking, type BookingAttendee, type SchedulerClient, type TimeSlot, } from "./core/client/scheduler";
7
9
  export { DEFAULT_API_BASE_URL, createTransport, type Transport, type TransportError, type TransportResult, } from "./core/client/transport";
8
10
  export { IDENTITY_INFO_ANSWER_KEYS, type DisclaimerAnswer, type DropdownAnswer, type EmailFormAnswer, type FileUploaderAnswer, type GraphicOptionsAnswer, type IdentityInfoAnswer, type IdentityInfoAnswerKey, type KnownAnswerState, type LongInputAnswer, type MMChoiceAnswer, type MultipleChoiceAnswer, type MultipleChoiceSingleAnswerAnswer, type MultipleOptionsAnswer, type SchedulerAnswer, type ShortInputAnswer, } from "./core/engine/answerStates";
9
11
  export { createFormEngine, type FormEngine, type FormEngineEvents, type FormEngineState, type ResolveNextStep, type ResolvedNextStep, } from "./core/engine/formEngine";
10
12
  export { DEFAULT_REDIRECT_TIMEOUT_MS, buildRedirectUrl, performRedirect, type RedirectType, } from "./core/engine/redirect";
11
13
  export { buildResponsesArray, createSubmitResponsePayload, createUpdateResponsePayload, type AnswerStates, type ExternalStates, type FormResponsePayload, type FormUpdateResponsePayload, type SingleFormResponse, } from "./core/engine/responsePayload";
14
+ export { type SchedulerBookingSummary, type SchedulerLifecycleEvent, type SchedulerProvider, } from "./core/engine/schedulerEvents";
12
15
  export { buildUrlData, constructUrlParamsObject, parseCookiesObject, type UrlData, } from "./core/engine/urlData";
13
16
  export { parsePrefillParams, parseQuestionId, type ParsedUrlQuestionId } from "./core/engine/urlPrefill";
14
17
  export { observeDropoff } from "./core/events/dropoffDetection";
@@ -1,4 +1,5 @@
1
1
  import type { FormEngine, FormEngineState } from "../core/engine/formEngine";
2
+
2
3
  export type UseSurfaceFormResult = {
3
4
  state: FormEngineState;
4
5
  setAnswer: FormEngine["setAnswer"];
@@ -1,46 +1,73 @@
1
1
  import { type EmailValidationResult } from "./core/client/emailValidation";
2
2
  import { type RuntimeConfig } from "./core/client/runtimeConfig";
3
+ import { type Transport } from "./core/client/transport";
3
4
  import { type FormEngine, type ResolveNextStep } from "./core/engine/formEngine";
4
5
  import type { LeadSource } from "./core/identity/identify";
5
6
  import { type TrackingSettings } from "./tracking/attachTracking";
7
+
6
8
  export type SurfaceFormsInitOptions = {
7
9
  environmentId: string;
8
10
  formId: string;
11
+
9
12
  steps?: Array<{
10
13
  id: string;
11
14
  endStepKind?: "thank_you" | "disqualified";
12
15
  }>;
16
+
13
17
  settings?: {
14
18
  trackPartialResponses?: boolean;
15
19
  trackCookies?: boolean;
16
20
  } & TrackingSettings;
17
21
  apiBaseUrl?: string;
22
+
18
23
  container?: Element;
24
+
19
25
  expectedQuestionIds?: string[];
26
+
20
27
  resolveNextStep?: ResolveNextStep;
28
+
21
29
  urlDataStateId?: string;
22
30
  source?: LeadSource;
31
+
23
32
  journey?: boolean;
33
+
24
34
  emailValidation?: boolean;
25
35
  preview?: boolean;
36
+
26
37
  previewToken?: string;
38
+
27
39
  resume?: {
28
40
  responseId: string;
29
41
  resumeToken: string;
30
42
  };
43
+
31
44
  debug?: boolean;
32
45
  meta?: Record<string, unknown>;
33
46
  };
34
- export type SurfaceForm = Pick<FormEngine, "setAnswer" | "setExternalState" | "next" | "back" | "goToStep" | "submit" | "disqualify" | "savePartial" | "flush" | "markViewed" | "on" | "state" | "subscribe"> & {
47
+ export type SurfaceForm = Pick<FormEngine, "setAnswer" | "setExternalState" | "next" | "back" | "goToStep" | "submit" | "disqualify" | "savePartial" | "notifyScheduler" | "flush" | "markViewed" | "on" | "state" | "subscribe"> & {
48
+
35
49
  identify: () => Promise<unknown>;
50
+
36
51
  validateEmail: (email: string) => Promise<EmailValidationResult>;
52
+
37
53
  mergeMeta: (partial: Record<string, unknown>) => void;
54
+
38
55
  capabilities: {
39
56
  enrichment: boolean;
40
57
  emailValidation: boolean;
41
58
  tracking: boolean;
42
59
  };
60
+
43
61
  runtimeConfig?: RuntimeConfig;
62
+
63
+ transport: Transport;
64
+
65
+ identity: () => {
66
+ fingerprint?: string;
67
+ leadSessionId?: string;
68
+ leadId?: string;
69
+ };
70
+ preview: boolean;
44
71
  destroy: () => void;
45
72
  };
46
73
  export declare const SurfaceForms: {
@@ -1,6 +1,7 @@
1
1
  import type { FormEngine } from "../core/engine/formEngine";
2
2
  import { type AdConversionRule } from "./conversionRules";
3
3
  import { type VendorSettings } from "./vendors";
4
+
4
5
  export type TrackingSettings = VendorSettings & {
5
6
  adsConversions?: AdConversionRule[];
6
7
  };
@@ -1,3 +1,4 @@
1
+
1
2
  export type AdConversionProvider = "x" | "meta" | "openai" | "ga4" | "linkedin";
2
3
  export type AdConversionTrigger = "reached_qualified" | "form_submitted" | "reached_step" | "form_started" | "step_submitted" | "email_provided" | "meeting_booked";
3
4
  export type AdConversionCondition = {
@@ -68,8 +69,10 @@ export declare const DEFAULT_OPENAI_EVENT_NAME = "lead_created";
68
69
  export declare const matchesCondition: (condition: AdConversionCondition, params: TrackingParams) => boolean;
69
70
  export declare const matchesConditions: (conditions: AdConversionCondition[], params: TrackingParams, operator?: "and" | "or") => boolean;
70
71
  export declare const ruleToConversionEvent: (rule: AdConversionRule) => ConversionEvent | null;
72
+
71
73
  export declare const selectFiringEvents: (rules: AdConversionRule[], trigger: AdConversionTrigger, params: TrackingParams, stepId?: string) => {
72
74
  rule: AdConversionRule;
73
75
  conversion: ConversionEvent;
74
76
  }[];
77
+
75
78
  export declare const fireConversion: (win: Window, conversion: ConversionEvent, ctx: FireContext) => boolean;
@@ -1,3 +1,4 @@
1
+
1
2
  export type LifecycleUrlData = {
2
3
  url: string;
3
4
  urlParams: Record<string, string>;
@@ -11,11 +12,13 @@ export type VendorSettings = {
11
12
  };
12
13
  };
13
14
  export type StepSubmittedPayload = LifecycleUrlData & {
15
+
14
16
  stepId: string;
15
17
  formId: string;
16
18
  emailProvided: boolean;
17
19
  meetingBooked: boolean;
18
20
  };
21
+
19
22
  export declare const createVendorTracker: (win: Window, settings: VendorSettings) => {
20
23
  formStarted: (formId: string, urlData: LifecycleUrlData) => void;
21
24
  stepSubmitted: (payload: StepSubmittedPayload) => void;