@parag.more.withsurface.com/forms-sdk 0.1.4 → 0.1.6

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 (191) hide show
  1. package/README.md +9 -4
  2. package/dist/index.cjs +1 -2737
  3. package/dist/index.mjs +1 -2714
  4. package/dist/react/index.cjs +1 -44
  5. package/dist/react/index.mjs +1 -21
  6. package/dist/surface-forms-sdk.min.js +21 -2
  7. package/dist/types/bind/bindForm.d.ts +2 -36
  8. package/dist/types/bind/bookingWidget.d.ts +29 -17
  9. package/dist/types/bind/scheduler/embedUtils.d.ts +50 -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 -4
  25. package/dist/types/core/client/responses.d.ts +3 -15
  26. package/dist/types/core/client/runtimeConfig.d.ts +40 -32
  27. package/dist/types/core/client/scheduler.d.ts +4 -27
  28. package/dist/types/core/client/transport.d.ts +4 -28
  29. package/dist/types/core/engine/answerAudit.d.ts +3 -12
  30. package/dist/types/core/engine/answerStates.d.ts +4 -17
  31. package/dist/types/core/engine/formEngine.d.ts +16 -53
  32. package/dist/types/core/engine/redirect.d.ts +1 -23
  33. package/dist/types/core/engine/responsePayload.d.ts +4 -28
  34. package/dist/types/core/engine/schedulerEvents.d.ts +40 -0
  35. package/dist/types/core/engine/urlData.d.ts +2 -17
  36. package/dist/types/core/engine/urlPrefill.d.ts +1 -9
  37. package/dist/types/core/events/dropoffDetection.d.ts +1 -14
  38. package/dist/types/core/events/emitter.d.ts +1 -17
  39. package/dist/types/core/events/formJourneyTracker.d.ts +1 -19
  40. package/dist/types/core/events/pushEvents.d.ts +2 -16
  41. package/dist/types/core/events/startedDetection.d.ts +1 -10
  42. package/dist/types/core/events/viewDetection.d.ts +1 -14
  43. package/dist/types/core/identity/browserFingerprint.d.ts +3 -19
  44. package/dist/types/core/identity/ensureIdentified.d.ts +1 -16
  45. package/dist/types/core/identity/identify.d.ts +1 -15
  46. package/dist/types/core/identity/journey.d.ts +3 -16
  47. package/dist/types/core/identity/journey.testStubs.d.ts +1 -2
  48. package/dist/types/core/identity/leadDataCache.d.ts +1 -16
  49. package/dist/types/enrichment/attachEnrichment.d.ts +1 -21
  50. package/dist/types/index.d.ts +5 -3
  51. package/dist/types/react/index.d.ts +0 -1
  52. package/dist/types/react/useSurfaceForm.d.ts +1 -11
  53. package/dist/types/surfaceForms.d.ts +28 -73
  54. package/dist/types/tracking/attachTracking.d.ts +1 -22
  55. package/dist/types/tracking/conversionRules.d.ts +3 -12
  56. package/dist/types/tracking/vendors.d.ts +3 -22
  57. package/dist/types/validation/attachEmailValidation.d.ts +0 -1
  58. package/docs/api.md +51 -39
  59. package/docs/reference/binding.md +86 -13
  60. package/docs/reference/clients.md +21 -1
  61. package/docs/reference/engine.md +5 -1
  62. package/docs/reference/events.md +4 -1
  63. package/docs/reference/identity.md +2 -3
  64. package/llms.txt +58 -10
  65. package/package.json +1 -1
  66. package/skills/surface-forms-sdk/SKILL.md +19 -6
  67. package/skills/surface-forms-sdk/patterns.md +30 -5
  68. package/dist/index.cjs.map +0 -7
  69. package/dist/index.mjs.map +0 -7
  70. package/dist/react/index.cjs.map +0 -7
  71. package/dist/react/index.mjs.map +0 -7
  72. package/dist/surface-forms-sdk.min.js.map +0 -7
  73. package/dist/types/bind/bindForm.d.ts.map +0 -1
  74. package/dist/types/bind/bindForm.test.d.ts +0 -2
  75. package/dist/types/bind/bindForm.test.d.ts.map +0 -1
  76. package/dist/types/bind/bookingWidget.d.ts.map +0 -1
  77. package/dist/types/bind/bookingWidget.test.d.ts +0 -2
  78. package/dist/types/bind/bookingWidget.test.d.ts.map +0 -1
  79. package/dist/types/core/client/emailValidation.d.ts.map +0 -1
  80. package/dist/types/core/client/emailValidation.test.d.ts +0 -2
  81. package/dist/types/core/client/emailValidation.test.d.ts.map +0 -1
  82. package/dist/types/core/client/responses.d.ts.map +0 -1
  83. package/dist/types/core/client/responses.test.d.ts +0 -2
  84. package/dist/types/core/client/responses.test.d.ts.map +0 -1
  85. package/dist/types/core/client/runtimeConfig.contract.test.d.ts +0 -2
  86. package/dist/types/core/client/runtimeConfig.contract.test.d.ts.map +0 -1
  87. package/dist/types/core/client/runtimeConfig.d.ts.map +0 -1
  88. package/dist/types/core/client/runtimeConfig.test.d.ts +0 -2
  89. package/dist/types/core/client/runtimeConfig.test.d.ts.map +0 -1
  90. package/dist/types/core/client/scheduler.contract.test.d.ts +0 -2
  91. package/dist/types/core/client/scheduler.contract.test.d.ts.map +0 -1
  92. package/dist/types/core/client/scheduler.d.ts.map +0 -1
  93. package/dist/types/core/client/scheduler.test.d.ts +0 -2
  94. package/dist/types/core/client/scheduler.test.d.ts.map +0 -1
  95. package/dist/types/core/client/transport.d.ts.map +0 -1
  96. package/dist/types/core/client/transport.test.d.ts +0 -2
  97. package/dist/types/core/client/transport.test.d.ts.map +0 -1
  98. package/dist/types/core/engine/answerAudit.d.ts.map +0 -1
  99. package/dist/types/core/engine/answerAudit.test.d.ts +0 -2
  100. package/dist/types/core/engine/answerAudit.test.d.ts.map +0 -1
  101. package/dist/types/core/engine/answerStates.contract.test.d.ts +0 -2
  102. package/dist/types/core/engine/answerStates.contract.test.d.ts.map +0 -1
  103. package/dist/types/core/engine/answerStates.d.ts.map +0 -1
  104. package/dist/types/core/engine/formEngine.d.ts.map +0 -1
  105. package/dist/types/core/engine/formEngine.test.d.ts +0 -2
  106. package/dist/types/core/engine/formEngine.test.d.ts.map +0 -1
  107. package/dist/types/core/engine/redirect.d.ts.map +0 -1
  108. package/dist/types/core/engine/redirect.test.d.ts +0 -2
  109. package/dist/types/core/engine/redirect.test.d.ts.map +0 -1
  110. package/dist/types/core/engine/responsePayload.contract.test.d.ts +0 -2
  111. package/dist/types/core/engine/responsePayload.contract.test.d.ts.map +0 -1
  112. package/dist/types/core/engine/responsePayload.d.ts.map +0 -1
  113. package/dist/types/core/engine/responsePayload.test.d.ts +0 -2
  114. package/dist/types/core/engine/responsePayload.test.d.ts.map +0 -1
  115. package/dist/types/core/engine/urlData.contract.test.d.ts +0 -2
  116. package/dist/types/core/engine/urlData.contract.test.d.ts.map +0 -1
  117. package/dist/types/core/engine/urlData.d.ts.map +0 -1
  118. package/dist/types/core/engine/urlData.test.d.ts +0 -2
  119. package/dist/types/core/engine/urlData.test.d.ts.map +0 -1
  120. package/dist/types/core/engine/urlPrefill.d.ts.map +0 -1
  121. package/dist/types/core/engine/urlPrefill.test.d.ts +0 -2
  122. package/dist/types/core/engine/urlPrefill.test.d.ts.map +0 -1
  123. package/dist/types/core/events/dropoffDetection.d.ts.map +0 -1
  124. package/dist/types/core/events/dropoffDetection.test.d.ts +0 -2
  125. package/dist/types/core/events/dropoffDetection.test.d.ts.map +0 -1
  126. package/dist/types/core/events/emitter.d.ts.map +0 -1
  127. package/dist/types/core/events/emitter.test.d.ts +0 -2
  128. package/dist/types/core/events/emitter.test.d.ts.map +0 -1
  129. package/dist/types/core/events/formJourneyTracker.contract.test.d.ts +0 -2
  130. package/dist/types/core/events/formJourneyTracker.contract.test.d.ts.map +0 -1
  131. package/dist/types/core/events/formJourneyTracker.d.ts.map +0 -1
  132. package/dist/types/core/events/formJourneyTracker.test.d.ts +0 -2
  133. package/dist/types/core/events/formJourneyTracker.test.d.ts.map +0 -1
  134. package/dist/types/core/events/pushEvents.contract.test.d.ts +0 -2
  135. package/dist/types/core/events/pushEvents.contract.test.d.ts.map +0 -1
  136. package/dist/types/core/events/pushEvents.d.ts.map +0 -1
  137. package/dist/types/core/events/pushEvents.test.d.ts +0 -2
  138. package/dist/types/core/events/pushEvents.test.d.ts.map +0 -1
  139. package/dist/types/core/events/startedDetection.d.ts.map +0 -1
  140. package/dist/types/core/events/startedDetection.test.d.ts +0 -2
  141. package/dist/types/core/events/startedDetection.test.d.ts.map +0 -1
  142. package/dist/types/core/events/viewDetection.d.ts.map +0 -1
  143. package/dist/types/core/events/viewDetection.test.d.ts +0 -2
  144. package/dist/types/core/events/viewDetection.test.d.ts.map +0 -1
  145. package/dist/types/core/identity/browserFingerprint.d.ts.map +0 -1
  146. package/dist/types/core/identity/browserFingerprint.test.d.ts +0 -2
  147. package/dist/types/core/identity/browserFingerprint.test.d.ts.map +0 -1
  148. package/dist/types/core/identity/ensureIdentified.d.ts.map +0 -1
  149. package/dist/types/core/identity/ensureIdentified.test.d.ts +0 -2
  150. package/dist/types/core/identity/ensureIdentified.test.d.ts.map +0 -1
  151. package/dist/types/core/identity/identify.contract.test.d.ts +0 -2
  152. package/dist/types/core/identity/identify.contract.test.d.ts.map +0 -1
  153. package/dist/types/core/identity/identify.d.ts.map +0 -1
  154. package/dist/types/core/identity/identify.test.d.ts +0 -2
  155. package/dist/types/core/identity/identify.test.d.ts.map +0 -1
  156. package/dist/types/core/identity/journey.contract.test.d.ts +0 -2
  157. package/dist/types/core/identity/journey.contract.test.d.ts.map +0 -1
  158. package/dist/types/core/identity/journey.d.ts.map +0 -1
  159. package/dist/types/core/identity/journey.test.d.ts +0 -2
  160. package/dist/types/core/identity/journey.test.d.ts.map +0 -1
  161. package/dist/types/core/identity/journey.testStubs.d.ts.map +0 -1
  162. package/dist/types/core/identity/leadDataCache.d.ts.map +0 -1
  163. package/dist/types/core/identity/leadDataCache.test.d.ts +0 -2
  164. package/dist/types/core/identity/leadDataCache.test.d.ts.map +0 -1
  165. package/dist/types/enrichment/attachEnrichment.d.ts.map +0 -1
  166. package/dist/types/enrichment/attachEnrichment.test.d.ts +0 -2
  167. package/dist/types/enrichment/attachEnrichment.test.d.ts.map +0 -1
  168. package/dist/types/index.d.ts.map +0 -1
  169. package/dist/types/react/index.d.ts.map +0 -1
  170. package/dist/types/react/ssr.test.d.ts +0 -2
  171. package/dist/types/react/ssr.test.d.ts.map +0 -1
  172. package/dist/types/react/useSurfaceForm.d.ts.map +0 -1
  173. package/dist/types/react/useSurfaceForm.test.d.ts +0 -2
  174. package/dist/types/react/useSurfaceForm.test.d.ts.map +0 -1
  175. package/dist/types/surfaceForms.d.ts.map +0 -1
  176. package/dist/types/surfaceForms.test.d.ts +0 -2
  177. package/dist/types/surfaceForms.test.d.ts.map +0 -1
  178. package/dist/types/tracking/attachTracking.d.ts.map +0 -1
  179. package/dist/types/tracking/attachTracking.test.d.ts +0 -2
  180. package/dist/types/tracking/attachTracking.test.d.ts.map +0 -1
  181. package/dist/types/tracking/conversionRules.contract.test.d.ts +0 -2
  182. package/dist/types/tracking/conversionRules.contract.test.d.ts.map +0 -1
  183. package/dist/types/tracking/conversionRules.d.ts.map +0 -1
  184. package/dist/types/tracking/conversionRules.test.d.ts +0 -2
  185. package/dist/types/tracking/conversionRules.test.d.ts.map +0 -1
  186. package/dist/types/tracking/vendors.d.ts.map +0 -1
  187. package/dist/types/tracking/vendors.test.d.ts +0 -2
  188. package/dist/types/tracking/vendors.test.d.ts.map +0 -1
  189. package/dist/types/validation/attachEmailValidation.d.ts.map +0 -1
  190. package/dist/types/validation/attachEmailValidation.test.d.ts +0 -2
  191. package/dist/types/validation/attachEmailValidation.test.d.ts.map +0 -1
package/README.md CHANGED
@@ -4,10 +4,10 @@ Build Surface forms as **your own pages**. The form record on Surface stays the
4
4
  data model — steps, questions, validation, enrichment, tracking settings — while
5
5
  your HTML/CSS/JS owns every pixel and every navigation decision. The SDK binds
6
6
  the two: a headless, dependency-free engine over Surface's public runtime
7
- endpoints, a `data-*` DOM binding layer, a React adapter, an unstyled booking
8
- widget for Surface schedulers, and settings-driven tag/conversion tracking
9
- (GTM/GA4/Meta/HubSpot + ad conversions). ~18 kB gzipped, zero runtime
10
- dependencies.
7
+ endpoints, a `data-*` DOM binding layer, a React adapter, embedded schedulers
8
+ (Surface's own + every provider native forms support) with automatic booking
9
+ tracking, and settings-driven tag/conversion tracking (GTM/GA4/Meta/HubSpot +
10
+ ad conversions). ~22 kB gzipped, zero runtime dependencies.
11
11
 
12
12
  > **Working with an AI agent?** This package ships agent-ready docs:
13
13
  > [`llms.txt`](llms.txt) is the binding contract and boot guide,
@@ -44,6 +44,11 @@ Highlights beyond binding:
44
44
 
45
45
  - **Headless + React** — drive everything with `setAnswer`/`submit`/`state`,
46
46
  or `useSurfaceForm` from `<package>/react`.
47
+ - **Embedded schedulers** — `mountScheduler({ form, container })` renders the
48
+ record's scheduler (Surface, Calendly, Cal.com, SavvyCal, Chili Piper,
49
+ HubSpot, RevenueHero, Zoom, Reclaim.ai, Clari), tracks the booking lifecycle
50
+ on `form.on("scheduler")`, and persists the booking automatically; an
51
+ unstyled widget remains for fully custom booking UIs.
47
52
  - **Resume** — persist the `saved` event's `{ responseId, resumeToken }` and
48
53
  pass `resume:` to continue a response later.
49
54
  - **Email validation** — `form.validateEmail()` on demand, or