@kanorio/sdk 1.1.0 → 1.2.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.
@@ -130,7 +130,7 @@ export interface paths {
130
130
  path?: never;
131
131
  cookie?: never;
132
132
  };
133
- /** Collections and their fields (self-describing). System collections also list virtualFields (projection-only fields such as blog segments/toc/contentHtml and taxonomy counts) with scope item|fieldData|expanded and a TypeScript type literal; a field whose shape is fixed (the seo field of blog, categories, tags and authors) carries tsType. */
133
+ /** Collections and their fields (self-describing). System collections also list virtualFields (projection-only fields such as blog segments/toc/contentHtml and taxonomy counts) with scope item|fieldData|expanded and a TypeScript type literal; a field whose shape is fixed (the seo field of blog, categories, tags and authors) carries tsType, and a system field whose value needs explaining (the blog cover_image, which is derived and can be an asset id or a URL) carries tsDoc. */
134
134
  get: operations["delivery_collections_list"];
135
135
  put?: never;
136
136
  post?: never;
@@ -447,7 +447,10 @@ export interface paths {
447
447
  };
448
448
  get?: never;
449
449
  put?: never;
450
- /** Submit answers to an online form */
450
+ /**
451
+ * Submit answers to an online form
452
+ * @description A 200 means the submission was stored. A challenge (or third-party widget token) stores one submission: sending other answers with one that was already used returns 400 VERIFICATION_EXPIRED, while sending exactly the same submission again returns 200 and stores nothing twice. After a rejected submission (INVALID_ANSWERS, DUPLICATE_SUBMISSION, RATE_LIMITED, a server error) the solved built-in challenge can be sent again. A submission is processed no sooner than 5 seconds after its challenge was issued; one that arrives earlier is held until then. Marketing consent is recorded only when consent is sent with the consentTextId from GET /forms/{id}. Requests that no real form produces (a filled honeypot field, a forged protection result, a challenge issued for another form) also get 200 and are discarded.
453
+ */
451
454
  post: operations["delivery_form_submit"];
452
455
  delete?: never;
453
456
  options?: never;
@@ -578,6 +581,521 @@ export interface components {
578
581
  };
579
582
  /** @enum {string} */
580
583
  ErrorCode: "BAD_HOST" | "COLLECTION_NOT_FOUND" | "DUPLICATE_SUBMISSION" | "FILE_TOO_LARGE" | "FILE_TYPE_NOT_ALLOWED" | "FORBIDDEN" | "FORM_NOT_FOUND" | "HEADER_NOT_FOUND" | "INVALID_ANSWERS" | "INVALID_BODY" | "INVALID_CURSOR" | "INVALID_KIND" | "INVALID_LIMIT" | "INVALID_PATH" | "INVALID_QUERY" | "ITEM_NOT_FOUND" | "NOT_PREVIEW" | "PAGE_NOT_FOUND" | "PAYLOAD_TOO_LARGE" | "PRODUCT_NOT_FOUND" | "QUERY_REQUIRED" | "QUERY_TIMEOUT" | "QUERY_TOO_LONG" | "QUERY_TOO_SHORT" | "RATE_LIMITED" | "SEARCH_BUSY" | "SITE_NOT_FOUND" | "TOO_MANY_PARAMS" | "UNAUTHORIZED" | "UNIT_NOT_FOUND" | "UNKNOWN_BOT" | "UNSUPPORTED_LOCALE" | "UPLOAD_UNAVAILABLE" | "UPSTREAM_UNAVAILABLE" | "VALIDATION" | "VERIFICATION_EXPIRED";
584
+ Form: {
585
+ id: string;
586
+ name: string;
587
+ /** @description Text shown under the form name. */
588
+ description: string | null;
589
+ /**
590
+ * @description ACTIVE accepts answers (within settings.openAt, settings.closeAt and settings.maxSubmissions); ARCHIVED is paused. DRAFT forms are not returned.
591
+ * @enum {string}
592
+ */
593
+ status: "DRAFT" | "ACTIVE" | "ARCHIVED";
594
+ /** @description The questions, in display order. Each one is discriminated by `type`. */
595
+ fields: components["schemas"]["FormField"][];
596
+ settings: components["schemas"]["FormSettings"];
597
+ /** @description Submissions received so far, not counting spam; compare with settings.maxSubmissions. */
598
+ submissionCount: number;
599
+ /** @description Id of the consent text for the current settings.marketingConsent mode. Send it back unchanged as consentTextId on submit; consent is recorded only when it matches. Null when consent is off. */
600
+ consentTextId: string | null;
601
+ /** @description The consent text to show the visitor, in the requested locale: the owner's own wording, or the platform default with the site name and submit button text filled in. Null when consent is off. */
602
+ consentText?: string | null;
603
+ /** @description Where to send the visitor after a successful submit, with the locale prefix already added. Null when not set, and null when the address has answers filled in (settings.redirectUrl contains {answers.<id>} or {submissionId}): in that case use redirectUrl of the submit response. The submit response always carries the address to use, so prefer it. */
604
+ redirectUrl?: string | null;
605
+ /** @description ISO 3166-1 alpha-2 country used for a phone question that sets no default country; the server parses national numbers with the same value. */
606
+ defaultPhoneCountry?: string | null;
607
+ /** @description The site's IANA time zone. "From today" bounds of date questions are computed in it, on the server too. */
608
+ timezone?: string | null;
609
+ } & {
610
+ [key: string]: unknown;
611
+ };
612
+ /** @description One question. `type` decides the other keys; `visibleWhen` makes it conditional (evaluate with visibleFieldIds from @kanorio/sdk/forms). */
613
+ FormField: {
614
+ id: string;
615
+ label: string;
616
+ description?: string;
617
+ /** @default false */
618
+ required: boolean;
619
+ contactMapping?: "name" | "email" | "phone" | string;
620
+ visibleWhen?: {
621
+ /**
622
+ * @default all
623
+ * @enum {string}
624
+ */
625
+ match: "all" | "any";
626
+ conditions: {
627
+ /**
628
+ * @default field
629
+ * @enum {string}
630
+ */
631
+ kind: "field" | "hidden";
632
+ ref: string;
633
+ /** @enum {string} */
634
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
635
+ value?: string | number;
636
+ }[];
637
+ };
638
+ /** @constant */
639
+ type: "short_text";
640
+ minLength?: number;
641
+ maxLength?: number;
642
+ pattern?: string;
643
+ patternMessage?: string;
644
+ } | {
645
+ id: string;
646
+ label: string;
647
+ description?: string;
648
+ /** @default false */
649
+ required: boolean;
650
+ contactMapping?: "name" | "email" | "phone" | string;
651
+ visibleWhen?: {
652
+ /**
653
+ * @default all
654
+ * @enum {string}
655
+ */
656
+ match: "all" | "any";
657
+ conditions: {
658
+ /**
659
+ * @default field
660
+ * @enum {string}
661
+ */
662
+ kind: "field" | "hidden";
663
+ ref: string;
664
+ /** @enum {string} */
665
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
666
+ value?: string | number;
667
+ }[];
668
+ };
669
+ /** @constant */
670
+ type: "long_text";
671
+ minLength?: number;
672
+ maxLength?: number;
673
+ } | {
674
+ id: string;
675
+ label: string;
676
+ description?: string;
677
+ required: unknown;
678
+ /**
679
+ * @default email
680
+ * @constant
681
+ */
682
+ contactMapping: "email";
683
+ visibleWhen?: {
684
+ /**
685
+ * @default all
686
+ * @enum {string}
687
+ */
688
+ match: "all" | "any";
689
+ conditions: {
690
+ /**
691
+ * @default field
692
+ * @enum {string}
693
+ */
694
+ kind: "field" | "hidden";
695
+ ref: string;
696
+ /** @enum {string} */
697
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
698
+ value?: string | number;
699
+ }[];
700
+ };
701
+ /** @constant */
702
+ type: "email";
703
+ } | {
704
+ id: string;
705
+ label: string;
706
+ description?: string;
707
+ /** @default false */
708
+ required: boolean;
709
+ /**
710
+ * @default phone
711
+ * @constant
712
+ */
713
+ contactMapping: "phone";
714
+ visibleWhen?: {
715
+ /**
716
+ * @default all
717
+ * @enum {string}
718
+ */
719
+ match: "all" | "any";
720
+ conditions: {
721
+ /**
722
+ * @default field
723
+ * @enum {string}
724
+ */
725
+ kind: "field" | "hidden";
726
+ ref: string;
727
+ /** @enum {string} */
728
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
729
+ value?: string | number;
730
+ }[];
731
+ };
732
+ /** @constant */
733
+ type: "phone";
734
+ defaultCountry?: string;
735
+ } | {
736
+ id: string;
737
+ label: string;
738
+ description?: string;
739
+ /** @default false */
740
+ required: boolean;
741
+ contactMapping?: "name" | "email" | "phone" | string;
742
+ visibleWhen?: {
743
+ /**
744
+ * @default all
745
+ * @enum {string}
746
+ */
747
+ match: "all" | "any";
748
+ conditions: {
749
+ /**
750
+ * @default field
751
+ * @enum {string}
752
+ */
753
+ kind: "field" | "hidden";
754
+ ref: string;
755
+ /** @enum {string} */
756
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
757
+ value?: string | number;
758
+ }[];
759
+ };
760
+ /** @constant */
761
+ type: "choice";
762
+ options: {
763
+ id: string;
764
+ label: string;
765
+ }[];
766
+ /** @default false */
767
+ allowMultiple: boolean;
768
+ /** @default false */
769
+ allowOther: boolean;
770
+ /**
771
+ * @default list
772
+ * @enum {string}
773
+ */
774
+ display: "list" | "dropdown";
775
+ minSelections?: number;
776
+ maxSelections?: number;
777
+ } | {
778
+ id: string;
779
+ label: string;
780
+ description?: string;
781
+ /** @default false */
782
+ required: boolean;
783
+ contactMapping?: "name" | "email" | "phone" | string;
784
+ visibleWhen?: {
785
+ /**
786
+ * @default all
787
+ * @enum {string}
788
+ */
789
+ match: "all" | "any";
790
+ conditions: {
791
+ /**
792
+ * @default field
793
+ * @enum {string}
794
+ */
795
+ kind: "field" | "hidden";
796
+ ref: string;
797
+ /** @enum {string} */
798
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
799
+ value?: string | number;
800
+ }[];
801
+ };
802
+ /** @constant */
803
+ type: "date";
804
+ range?: {
805
+ min?: {
806
+ /** @constant */
807
+ type: "today";
808
+ /** @default 0 */
809
+ offsetDays: number;
810
+ } | {
811
+ /** @constant */
812
+ type: "date";
813
+ value: string;
814
+ };
815
+ max?: {
816
+ /** @constant */
817
+ type: "today";
818
+ /** @default 0 */
819
+ offsetDays: number;
820
+ } | {
821
+ /** @constant */
822
+ type: "date";
823
+ value: string;
824
+ };
825
+ };
826
+ } | {
827
+ id: string;
828
+ label: string;
829
+ description?: string;
830
+ /** @default false */
831
+ required: boolean;
832
+ contactMapping?: "name" | "email" | "phone" | string;
833
+ visibleWhen?: {
834
+ /**
835
+ * @default all
836
+ * @enum {string}
837
+ */
838
+ match: "all" | "any";
839
+ conditions: {
840
+ /**
841
+ * @default field
842
+ * @enum {string}
843
+ */
844
+ kind: "field" | "hidden";
845
+ ref: string;
846
+ /** @enum {string} */
847
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
848
+ value?: string | number;
849
+ }[];
850
+ };
851
+ /** @constant */
852
+ type: "time";
853
+ } | {
854
+ id: string;
855
+ label: string;
856
+ description?: string;
857
+ /** @default false */
858
+ required: boolean;
859
+ contactMapping?: "name" | "email" | "phone" | string;
860
+ visibleWhen?: {
861
+ /**
862
+ * @default all
863
+ * @enum {string}
864
+ */
865
+ match: "all" | "any";
866
+ conditions: {
867
+ /**
868
+ * @default field
869
+ * @enum {string}
870
+ */
871
+ kind: "field" | "hidden";
872
+ ref: string;
873
+ /** @enum {string} */
874
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
875
+ value?: string | number;
876
+ }[];
877
+ };
878
+ /** @constant */
879
+ type: "file";
880
+ /** @default 1 */
881
+ maxFiles: number;
882
+ /** @default [] */
883
+ accept: string[];
884
+ } | {
885
+ id: string;
886
+ label: string;
887
+ description?: string;
888
+ /** @default false */
889
+ required: boolean;
890
+ contactMapping?: "name" | "email" | "phone" | string;
891
+ visibleWhen?: {
892
+ /**
893
+ * @default all
894
+ * @enum {string}
895
+ */
896
+ match: "all" | "any";
897
+ conditions: {
898
+ /**
899
+ * @default field
900
+ * @enum {string}
901
+ */
902
+ kind: "field" | "hidden";
903
+ ref: string;
904
+ /** @enum {string} */
905
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
906
+ value?: string | number;
907
+ }[];
908
+ };
909
+ /** @constant */
910
+ type: "rating";
911
+ /** @default 5 */
912
+ max: number;
913
+ /**
914
+ * @default star
915
+ * @enum {string}
916
+ */
917
+ icon: "star" | "heart" | "thumb";
918
+ } | {
919
+ id: string;
920
+ label: string;
921
+ description?: string;
922
+ /** @default false */
923
+ required: boolean;
924
+ contactMapping?: "name" | "email" | "phone" | string;
925
+ visibleWhen?: {
926
+ /**
927
+ * @default all
928
+ * @enum {string}
929
+ */
930
+ match: "all" | "any";
931
+ conditions: {
932
+ /**
933
+ * @default field
934
+ * @enum {string}
935
+ */
936
+ kind: "field" | "hidden";
937
+ ref: string;
938
+ /** @enum {string} */
939
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
940
+ value?: string | number;
941
+ }[];
942
+ };
943
+ /** @constant */
944
+ type: "number";
945
+ min?: number;
946
+ max?: number;
947
+ /** @default false */
948
+ integer: boolean;
949
+ } | {
950
+ id: string;
951
+ label: string;
952
+ description?: string;
953
+ /** @default false */
954
+ required: boolean;
955
+ contactMapping?: "name" | "email" | "phone" | string;
956
+ visibleWhen?: {
957
+ /**
958
+ * @default all
959
+ * @enum {string}
960
+ */
961
+ match: "all" | "any";
962
+ conditions: {
963
+ /**
964
+ * @default field
965
+ * @enum {string}
966
+ */
967
+ kind: "field" | "hidden";
968
+ ref: string;
969
+ /** @enum {string} */
970
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
971
+ value?: string | number;
972
+ }[];
973
+ };
974
+ /** @constant */
975
+ type: "url";
976
+ } | {
977
+ id: string;
978
+ label: string;
979
+ description?: string;
980
+ /** @default false */
981
+ required: boolean;
982
+ /** @constant */
983
+ contactMapping?: "address";
984
+ visibleWhen?: {
985
+ /**
986
+ * @default all
987
+ * @enum {string}
988
+ */
989
+ match: "all" | "any";
990
+ conditions: {
991
+ /**
992
+ * @default field
993
+ * @enum {string}
994
+ */
995
+ kind: "field" | "hidden";
996
+ ref: string;
997
+ /** @enum {string} */
998
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
999
+ value?: string | number;
1000
+ }[];
1001
+ };
1002
+ /** @constant */
1003
+ type: "address";
1004
+ defaultCountry?: string;
1005
+ /** @default [] */
1006
+ countries: string[];
1007
+ /** @default false */
1008
+ askRecipientName: boolean;
1009
+ } | {
1010
+ id: string;
1011
+ label: string;
1012
+ description?: string;
1013
+ /** @default false */
1014
+ required: boolean;
1015
+ /** @constant */
1016
+ contactMapping?: "tax_identity";
1017
+ visibleWhen?: {
1018
+ /**
1019
+ * @default all
1020
+ * @enum {string}
1021
+ */
1022
+ match: "all" | "any";
1023
+ conditions: {
1024
+ /**
1025
+ * @default field
1026
+ * @enum {string}
1027
+ */
1028
+ kind: "field" | "hidden";
1029
+ ref: string;
1030
+ /** @enum {string} */
1031
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
1032
+ value?: string | number;
1033
+ }[];
1034
+ };
1035
+ /** @constant */
1036
+ type: "tax_id";
1037
+ defaultCountry?: string;
1038
+ /** @default [] */
1039
+ countries: string[];
1040
+ companyNameFieldId?: string;
1041
+ } | {
1042
+ id: string;
1043
+ /** @constant */
1044
+ type: "statement";
1045
+ label: string;
1046
+ description?: string;
1047
+ required: unknown;
1048
+ contactMapping?: unknown;
1049
+ visibleWhen?: {
1050
+ /**
1051
+ * @default all
1052
+ * @enum {string}
1053
+ */
1054
+ match: "all" | "any";
1055
+ conditions: {
1056
+ /**
1057
+ * @default field
1058
+ * @enum {string}
1059
+ */
1060
+ kind: "field" | "hidden";
1061
+ ref: string;
1062
+ /** @enum {string} */
1063
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
1064
+ value?: string | number;
1065
+ }[];
1066
+ };
1067
+ };
1068
+ FormSettings: {
1069
+ submitLabel?: string;
1070
+ successMessage?: string;
1071
+ redirectUrl?: string;
1072
+ /**
1073
+ * @default off
1074
+ * @enum {string}
1075
+ */
1076
+ marketingConsent: "off" | "checkbox" | "submit";
1077
+ consentText?: {
1078
+ checkbox?: string;
1079
+ submit?: string;
1080
+ };
1081
+ /** @default false */
1082
+ limitOnePerContact: boolean;
1083
+ /** Format: date-time */
1084
+ openAt?: string;
1085
+ /** Format: date-time */
1086
+ closeAt?: string;
1087
+ maxSubmissions?: number;
1088
+ /**
1089
+ * @default general
1090
+ * @enum {string}
1091
+ */
1092
+ replyKind: "inquiry" | "booking" | "event" | "application" | "signup" | "feedback" | "general";
1093
+ /** @default [] */
1094
+ hiddenFields: {
1095
+ id: string;
1096
+ label?: string;
1097
+ }[];
1098
+ };
581
1099
  SiteLocale: {
582
1100
  /** @description BCP 47 locale code (`en-US`, `zh-Hant`); pass it (or `pathPrefix`) as `?locale=` */
583
1101
  locale: string;
@@ -1903,9 +2421,7 @@ export interface operations {
1903
2421
  };
1904
2422
  content: {
1905
2423
  "application/json": {
1906
- form: {
1907
- [key: string]: unknown;
1908
- };
2424
+ form: components["schemas"]["Form"];
1909
2425
  };
1910
2426
  };
1911
2427
  };
@@ -2144,7 +2660,7 @@ export interface operations {
2144
2660
  * @enum {string}
2145
2661
  */
2146
2662
  consent?: "checked" | "submit_statement";
2147
- /** @description Id of the consent text the visitor saw (from GET /forms/{id}). */
2663
+ /** @description Id of the consent text the visitor saw (consentTextId from GET /forms/{id}, whose consentText is the text to show). Required for consent to be recorded: without it, or when it no longer matches the form's current text, the submission is stored without consent. */
2148
2664
  consentTextId?: string;
2149
2665
  locale?: string;
2150
2666
  /** @description Path of the page the form was on, for the submission record. */
@@ -2174,8 +2690,15 @@ export interface operations {
2174
2690
  };
2175
2691
  content: {
2176
2692
  "application/json": {
2177
- /** @enum {string} */
2693
+ /**
2694
+ * @description Present when the form did not take the submission because of its own state. Nothing was saved.
2695
+ * @enum {string}
2696
+ */
2178
2697
  state?: "closed" | "not_open" | "full";
2698
+ /** @description Id of this submission. Absent when state is present. */
2699
+ submissionId?: string;
2700
+ /** @description Where to send the visitor now, when the form has a redirect after submit: a path on the site (with the locale prefix of the page the form was on) or an https URL, which can be on another site. Answers and the submission id are already filled in and percent-encoded. Absent when the form has no redirect. */
2701
+ redirectUrl?: string;
2179
2702
  };
2180
2703
  };
2181
2704
  };