@kanorio/sdk 1.1.0 → 1.3.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: the cover the author picked, an asset id or null, never derived and never a URL) carries tsDoc. A single-item collection (site settings, homepage sections) has singleton: true; read its one item at /collections/{key}/item. */
134
134
  get: operations["delivery_collections_list"];
135
135
  put?: never;
136
136
  post?: never;
@@ -174,6 +174,26 @@ export interface paths {
174
174
  patch?: never;
175
175
  trace?: never;
176
176
  };
177
+ "/collections/{key}/item": {
178
+ parameters: {
179
+ query?: never;
180
+ header?: never;
181
+ path?: never;
182
+ cookie?: never;
183
+ };
184
+ /**
185
+ * The item of a single-item collection
186
+ * @description Single-item collections (singleton: true in GET /collections) hold content that exists once, such as site settings or homepage sections. This returns their one published item in the same shape as GET /collections/{key}/items/{slug}, so no slug is needed. 404 ITEM_NOT_FOUND when nothing is published yet, or when the collection is not a single-item collection (read its items at /collections/{key}/items).
187
+ */
188
+ get: operations["delivery_collection_singleton"];
189
+ put?: never;
190
+ post?: never;
191
+ delete?: never;
192
+ options?: never;
193
+ head?: never;
194
+ patch?: never;
195
+ trace?: never;
196
+ };
177
197
  "/feed": {
178
198
  parameters: {
179
199
  query?: never;
@@ -359,7 +379,10 @@ export interface paths {
359
379
  };
360
380
  get?: never;
361
381
  put?: never;
362
- /** Record an AI crawler visit from an external storefront edge middleware (per-IP rate-limited) */
382
+ /**
383
+ * Record an AI crawler visit from your own server's edge middleware (requires a server key)
384
+ * @description Called by your server, never by a browser: send the server key in `X-Kanorio-Server-Key` and the crawler's IP address in `X-Kanorio-Visitor-IP`. Without a key the request is refused with `401 SERVER_KEY_REQUIRED`; an invalid key gets `401 UNAUTHORIZED`. `createKanorioMiddleware` in `@kanorio/sdk/edge` sends it when you pass `serverKey`.
385
+ */
363
386
  post: operations["delivery_analytics_bot_hit"];
364
387
  delete?: never;
365
388
  options?: never;
@@ -447,7 +470,10 @@ export interface paths {
447
470
  };
448
471
  get?: never;
449
472
  put?: never;
450
- /** Submit answers to an online form */
473
+ /**
474
+ * Submit answers to an online form
475
+ * @description A 200 with a submissionId means the submission was stored; a 200 with state means the form did not take it and nothing 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 with the id of the stored submission and stores nothing twice. If the first is still being processed after 5 seconds, the second gets 503 UPSTREAM_UNAVAILABLE: send it again with the same challenge. 500 INTERNAL means Kanorio failed while processing the submission and nothing was stored: a third-party widget token is used up, so get a new one before sending again. After a submission that was not stored for a reason that can change (INVALID_ANSWERS, RATE_LIMITED, INTERNAL, or a form that is closed, not open yet or full) the solved built-in challenge can be sent again. DUPLICATE_SUBMISSION uses up the challenge: the same submission sent again gets the same answer, and different answers need a new challenge. 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.
476
+ */
451
477
  post: operations["delivery_form_submit"];
452
478
  delete?: never;
453
479
  options?: never;
@@ -577,7 +603,524 @@ export interface components {
577
603
  };
578
604
  };
579
605
  /** @enum {string} */
580
- 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";
606
+ ErrorCode: "BAD_HOST" | "COLLECTION_NOT_FOUND" | "DUPLICATE_SUBMISSION" | "FILE_TOO_LARGE" | "FILE_TYPE_NOT_ALLOWED" | "FORBIDDEN" | "FORM_NOT_FOUND" | "HEADER_NOT_FOUND" | "INTERNAL" | "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" | "SERVER_KEY_REQUIRED" | "SITE_NOT_FOUND" | "TOO_MANY_PARAMS" | "UNAUTHORIZED" | "UNIT_NOT_FOUND" | "UNKNOWN_BOT" | "UNSUPPORTED_LOCALE" | "UPLOAD_UNAVAILABLE" | "UPSTREAM_UNAVAILABLE" | "VALIDATION" | "VERIFICATION_EXPIRED";
607
+ Form: {
608
+ id: string;
609
+ name: string;
610
+ /** @description Text shown under the form name. */
611
+ description: string | null;
612
+ /**
613
+ * @description ACTIVE accepts answers (within settings.openAt, settings.closeAt and settings.maxSubmissions); ARCHIVED is paused. DRAFT forms are not returned.
614
+ * @enum {string}
615
+ */
616
+ status: "DRAFT" | "ACTIVE" | "ARCHIVED";
617
+ /** @description The questions, in display order. Each one is discriminated by `type`. */
618
+ fields: components["schemas"]["FormField"][];
619
+ settings: components["schemas"]["FormSettings"];
620
+ /** @description Submissions received so far, not counting spam; compare with settings.maxSubmissions. */
621
+ submissionCount: number;
622
+ /** @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. */
623
+ consentTextId: string | null;
624
+ /** @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. */
625
+ consentText: string | null;
626
+ /** @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. */
627
+ redirectUrl: string | null;
628
+ /** @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. */
629
+ defaultPhoneCountry: string | null;
630
+ /** @description The site's IANA time zone. "From today" bounds of date questions are computed in it, on the server too. */
631
+ timezone: string | null;
632
+ } & {
633
+ [key: string]: unknown;
634
+ };
635
+ /** @description One question. `type` decides the other keys; `visibleWhen` makes it conditional (evaluate with visibleFieldIds from @kanorio/sdk/forms). */
636
+ FormField: {
637
+ id: string;
638
+ label: string;
639
+ description?: string;
640
+ /** @default false */
641
+ required: boolean;
642
+ contactMapping?: "name" | "email" | "phone" | string;
643
+ visibleWhen?: {
644
+ /**
645
+ * @default all
646
+ * @enum {string}
647
+ */
648
+ match: "all" | "any";
649
+ conditions: {
650
+ /**
651
+ * @default field
652
+ * @enum {string}
653
+ */
654
+ kind: "field" | "hidden";
655
+ ref: string;
656
+ /** @enum {string} */
657
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
658
+ value?: string | number;
659
+ }[];
660
+ };
661
+ /** @constant */
662
+ type: "short_text";
663
+ minLength?: number;
664
+ maxLength?: number;
665
+ pattern?: string;
666
+ patternMessage?: string;
667
+ } | {
668
+ id: string;
669
+ label: string;
670
+ description?: string;
671
+ /** @default false */
672
+ required: boolean;
673
+ contactMapping?: "name" | "email" | "phone" | string;
674
+ visibleWhen?: {
675
+ /**
676
+ * @default all
677
+ * @enum {string}
678
+ */
679
+ match: "all" | "any";
680
+ conditions: {
681
+ /**
682
+ * @default field
683
+ * @enum {string}
684
+ */
685
+ kind: "field" | "hidden";
686
+ ref: string;
687
+ /** @enum {string} */
688
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
689
+ value?: string | number;
690
+ }[];
691
+ };
692
+ /** @constant */
693
+ type: "long_text";
694
+ minLength?: number;
695
+ maxLength?: number;
696
+ } | {
697
+ id: string;
698
+ label: string;
699
+ description?: string;
700
+ /** @constant */
701
+ required: true;
702
+ /**
703
+ * @default email
704
+ * @constant
705
+ */
706
+ contactMapping: "email";
707
+ visibleWhen?: {
708
+ /**
709
+ * @default all
710
+ * @enum {string}
711
+ */
712
+ match: "all" | "any";
713
+ conditions: {
714
+ /**
715
+ * @default field
716
+ * @enum {string}
717
+ */
718
+ kind: "field" | "hidden";
719
+ ref: string;
720
+ /** @enum {string} */
721
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
722
+ value?: string | number;
723
+ }[];
724
+ };
725
+ /** @constant */
726
+ type: "email";
727
+ } | {
728
+ id: string;
729
+ label: string;
730
+ description?: string;
731
+ /** @default false */
732
+ required: boolean;
733
+ /**
734
+ * @default phone
735
+ * @constant
736
+ */
737
+ contactMapping: "phone";
738
+ visibleWhen?: {
739
+ /**
740
+ * @default all
741
+ * @enum {string}
742
+ */
743
+ match: "all" | "any";
744
+ conditions: {
745
+ /**
746
+ * @default field
747
+ * @enum {string}
748
+ */
749
+ kind: "field" | "hidden";
750
+ ref: string;
751
+ /** @enum {string} */
752
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
753
+ value?: string | number;
754
+ }[];
755
+ };
756
+ /** @constant */
757
+ type: "phone";
758
+ defaultCountry?: string;
759
+ } | {
760
+ id: string;
761
+ label: string;
762
+ description?: string;
763
+ /** @default false */
764
+ required: boolean;
765
+ contactMapping?: "name" | "email" | "phone" | string;
766
+ visibleWhen?: {
767
+ /**
768
+ * @default all
769
+ * @enum {string}
770
+ */
771
+ match: "all" | "any";
772
+ conditions: {
773
+ /**
774
+ * @default field
775
+ * @enum {string}
776
+ */
777
+ kind: "field" | "hidden";
778
+ ref: string;
779
+ /** @enum {string} */
780
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
781
+ value?: string | number;
782
+ }[];
783
+ };
784
+ /** @constant */
785
+ type: "choice";
786
+ options: {
787
+ id: string;
788
+ label: string;
789
+ }[];
790
+ /** @default false */
791
+ allowMultiple: boolean;
792
+ /** @default false */
793
+ allowOther: boolean;
794
+ /**
795
+ * @default list
796
+ * @enum {string}
797
+ */
798
+ display: "list" | "dropdown";
799
+ minSelections?: number;
800
+ maxSelections?: number;
801
+ } | {
802
+ id: string;
803
+ label: string;
804
+ description?: string;
805
+ /** @default false */
806
+ required: boolean;
807
+ contactMapping?: "name" | "email" | "phone" | string;
808
+ visibleWhen?: {
809
+ /**
810
+ * @default all
811
+ * @enum {string}
812
+ */
813
+ match: "all" | "any";
814
+ conditions: {
815
+ /**
816
+ * @default field
817
+ * @enum {string}
818
+ */
819
+ kind: "field" | "hidden";
820
+ ref: string;
821
+ /** @enum {string} */
822
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
823
+ value?: string | number;
824
+ }[];
825
+ };
826
+ /** @constant */
827
+ type: "date";
828
+ range?: {
829
+ min?: {
830
+ /** @constant */
831
+ type: "today";
832
+ /** @default 0 */
833
+ offsetDays: number;
834
+ } | {
835
+ /** @constant */
836
+ type: "date";
837
+ value: string;
838
+ };
839
+ max?: {
840
+ /** @constant */
841
+ type: "today";
842
+ /** @default 0 */
843
+ offsetDays: number;
844
+ } | {
845
+ /** @constant */
846
+ type: "date";
847
+ value: string;
848
+ };
849
+ };
850
+ } | {
851
+ id: string;
852
+ label: string;
853
+ description?: string;
854
+ /** @default false */
855
+ required: boolean;
856
+ contactMapping?: "name" | "email" | "phone" | string;
857
+ visibleWhen?: {
858
+ /**
859
+ * @default all
860
+ * @enum {string}
861
+ */
862
+ match: "all" | "any";
863
+ conditions: {
864
+ /**
865
+ * @default field
866
+ * @enum {string}
867
+ */
868
+ kind: "field" | "hidden";
869
+ ref: string;
870
+ /** @enum {string} */
871
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
872
+ value?: string | number;
873
+ }[];
874
+ };
875
+ /** @constant */
876
+ type: "time";
877
+ } | {
878
+ id: string;
879
+ label: string;
880
+ description?: string;
881
+ /** @default false */
882
+ required: boolean;
883
+ contactMapping?: "name" | "email" | "phone" | string;
884
+ visibleWhen?: {
885
+ /**
886
+ * @default all
887
+ * @enum {string}
888
+ */
889
+ match: "all" | "any";
890
+ conditions: {
891
+ /**
892
+ * @default field
893
+ * @enum {string}
894
+ */
895
+ kind: "field" | "hidden";
896
+ ref: string;
897
+ /** @enum {string} */
898
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
899
+ value?: string | number;
900
+ }[];
901
+ };
902
+ /** @constant */
903
+ type: "file";
904
+ /** @default 1 */
905
+ maxFiles: number;
906
+ /** @default [] */
907
+ accept: string[];
908
+ } | {
909
+ id: string;
910
+ label: string;
911
+ description?: string;
912
+ /** @default false */
913
+ required: boolean;
914
+ contactMapping?: "name" | "email" | "phone" | string;
915
+ visibleWhen?: {
916
+ /**
917
+ * @default all
918
+ * @enum {string}
919
+ */
920
+ match: "all" | "any";
921
+ conditions: {
922
+ /**
923
+ * @default field
924
+ * @enum {string}
925
+ */
926
+ kind: "field" | "hidden";
927
+ ref: string;
928
+ /** @enum {string} */
929
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
930
+ value?: string | number;
931
+ }[];
932
+ };
933
+ /** @constant */
934
+ type: "rating";
935
+ /** @default 5 */
936
+ max: number;
937
+ /**
938
+ * @default star
939
+ * @enum {string}
940
+ */
941
+ icon: "star" | "heart" | "thumb";
942
+ } | {
943
+ id: string;
944
+ label: string;
945
+ description?: string;
946
+ /** @default false */
947
+ required: boolean;
948
+ contactMapping?: "name" | "email" | "phone" | string;
949
+ visibleWhen?: {
950
+ /**
951
+ * @default all
952
+ * @enum {string}
953
+ */
954
+ match: "all" | "any";
955
+ conditions: {
956
+ /**
957
+ * @default field
958
+ * @enum {string}
959
+ */
960
+ kind: "field" | "hidden";
961
+ ref: string;
962
+ /** @enum {string} */
963
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
964
+ value?: string | number;
965
+ }[];
966
+ };
967
+ /** @constant */
968
+ type: "number";
969
+ min?: number;
970
+ max?: number;
971
+ /** @default false */
972
+ integer: boolean;
973
+ } | {
974
+ id: string;
975
+ label: string;
976
+ description?: string;
977
+ /** @default false */
978
+ required: boolean;
979
+ contactMapping?: "name" | "email" | "phone" | string;
980
+ visibleWhen?: {
981
+ /**
982
+ * @default all
983
+ * @enum {string}
984
+ */
985
+ match: "all" | "any";
986
+ conditions: {
987
+ /**
988
+ * @default field
989
+ * @enum {string}
990
+ */
991
+ kind: "field" | "hidden";
992
+ ref: string;
993
+ /** @enum {string} */
994
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
995
+ value?: string | number;
996
+ }[];
997
+ };
998
+ /** @constant */
999
+ type: "url";
1000
+ } | {
1001
+ id: string;
1002
+ label: string;
1003
+ description?: string;
1004
+ /** @default false */
1005
+ required: boolean;
1006
+ /** @constant */
1007
+ contactMapping?: "address";
1008
+ visibleWhen?: {
1009
+ /**
1010
+ * @default all
1011
+ * @enum {string}
1012
+ */
1013
+ match: "all" | "any";
1014
+ conditions: {
1015
+ /**
1016
+ * @default field
1017
+ * @enum {string}
1018
+ */
1019
+ kind: "field" | "hidden";
1020
+ ref: string;
1021
+ /** @enum {string} */
1022
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
1023
+ value?: string | number;
1024
+ }[];
1025
+ };
1026
+ /** @constant */
1027
+ type: "address";
1028
+ defaultCountry?: string;
1029
+ /** @default [] */
1030
+ countries: string[];
1031
+ /** @default false */
1032
+ askRecipientName: boolean;
1033
+ } | {
1034
+ id: string;
1035
+ label: string;
1036
+ description?: string;
1037
+ /** @default false */
1038
+ required: boolean;
1039
+ /** @constant */
1040
+ contactMapping?: "tax_identity";
1041
+ visibleWhen?: {
1042
+ /**
1043
+ * @default all
1044
+ * @enum {string}
1045
+ */
1046
+ match: "all" | "any";
1047
+ conditions: {
1048
+ /**
1049
+ * @default field
1050
+ * @enum {string}
1051
+ */
1052
+ kind: "field" | "hidden";
1053
+ ref: string;
1054
+ /** @enum {string} */
1055
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
1056
+ value?: string | number;
1057
+ }[];
1058
+ };
1059
+ /** @constant */
1060
+ type: "tax_id";
1061
+ defaultCountry?: string;
1062
+ /** @default [] */
1063
+ countries: string[];
1064
+ companyNameFieldId?: string;
1065
+ } | {
1066
+ id: string;
1067
+ /** @constant */
1068
+ type: "statement";
1069
+ label: string;
1070
+ description?: string;
1071
+ /** @constant */
1072
+ required: false;
1073
+ contactMapping?: never;
1074
+ visibleWhen?: {
1075
+ /**
1076
+ * @default all
1077
+ * @enum {string}
1078
+ */
1079
+ match: "all" | "any";
1080
+ conditions: {
1081
+ /**
1082
+ * @default field
1083
+ * @enum {string}
1084
+ */
1085
+ kind: "field" | "hidden";
1086
+ ref: string;
1087
+ /** @enum {string} */
1088
+ op: "answered" | "not_answered" | "includes" | "not_includes" | "equals" | "not_equals" | "contains" | "gt" | "gte" | "lt" | "lte";
1089
+ value?: string | number;
1090
+ }[];
1091
+ };
1092
+ };
1093
+ FormSettings: {
1094
+ submitLabel?: string;
1095
+ successMessage?: string;
1096
+ redirectUrl?: string;
1097
+ /**
1098
+ * @default off
1099
+ * @enum {string}
1100
+ */
1101
+ marketingConsent: "off" | "checkbox" | "submit";
1102
+ consentText?: {
1103
+ checkbox?: string;
1104
+ submit?: string;
1105
+ };
1106
+ /** @default false */
1107
+ limitOnePerContact: boolean;
1108
+ /** Format: date-time */
1109
+ openAt?: string;
1110
+ /** Format: date-time */
1111
+ closeAt?: string;
1112
+ maxSubmissions?: number;
1113
+ /**
1114
+ * @default general
1115
+ * @enum {string}
1116
+ */
1117
+ replyKind: "inquiry" | "booking" | "event" | "application" | "signup" | "feedback" | "general";
1118
+ /** @default [] */
1119
+ hiddenFields: {
1120
+ id: string;
1121
+ label?: string;
1122
+ }[];
1123
+ };
581
1124
  SiteLocale: {
582
1125
  /** @description BCP 47 locale code (`en-US`, `zh-Hant`); pass it (or `pathPrefix`) as `?locale=` */
583
1126
  locale: string;
@@ -589,13 +1132,18 @@ export interface components {
589
1132
  };
590
1133
  SiteMeta: {
591
1134
  id: string;
1135
+ /** @description The site's display name (the brand display name, or the site name when none is set). With `locale`, its translation in that locale; untranslated falls back to the primary locale. */
592
1136
  name: string | null;
1137
+ /** @description The site description. With `locale`, its translation in that locale; untranslated falls back to the primary locale. */
593
1138
  description: string | null;
1139
+ /** @description The site's primary locale code (same as `primaryLocale`), whatever `locale` was requested */
594
1140
  locale: string | null;
595
1141
  /** @description Primary locale code; its pages have no URL prefix */
596
- primaryLocale?: string | null;
597
- /** @description Published locales (primary first). Each secondary locale lives under `/{pathPrefix}/`. */
598
- locales?: components["schemas"]["SiteLocale"][];
1142
+ primaryLocale: string | null;
1143
+ /** @description Live locales (primary first; a single-language site lists only the primary locale). Each secondary locale lives under `/{pathPrefix}/`. */
1144
+ locales: components["schemas"]["SiteLocale"][];
1145
+ /** @description Locale of `name` and `description`: the requested locale when either has a translation in it, otherwise the primary locale */
1146
+ resolvedLocale: string | null;
599
1147
  timezone: string | null;
600
1148
  currency: string | null;
601
1149
  /** @enum {string} */
@@ -831,10 +1379,13 @@ export interface components {
831
1379
  };
832
1380
  Asset: {
833
1381
  assetId: string;
1382
+ /** @description Where to get the file. For an image this is the image at its original size (width x height), re-encoded by the image edge: replace the last path segment with a size such as w=800,fit=scale-down for a smaller one (imageUrl and srcSet in @kanorio/sdk do it for you). The URL changes when the file is replaced, so look it up on every response instead of storing it. */
834
1383
  url: string;
1384
+ /** @description Pixel width of the original; url delivers this size. null when unknown. */
835
1385
  width?: number | null;
1386
+ /** @description Pixel height of the original; url delivers this size. null when unknown. */
836
1387
  height?: number | null;
837
- /** @description Alternative text: the alt written where the image is used, otherwise the asset's default alt text set in the media library; null when neither exists. */
1388
+ /** @description Alternative text: the asset's default alt text set in the media library, or the alt written next to the image in rich text and the share image; null when neither exists. With `locale` (another than the primary), the media library alt is that locale's version when it has one, otherwise the primary one. For an image or gallery field, an item's `imageAlt` overrides it where set. */
838
1389
  alt?: string | null;
839
1390
  /** @description true when url is the watermarked version of the image (the site has a watermark on and the image is used where it applies). For images uploaded or replaced with a new version after the watermark was turned on, url is a low-resolution placeholder (or empty) until the watermarked version is ready; the original is never returned. */
840
1391
  watermarked?: boolean;
@@ -878,20 +1429,33 @@ export interface components {
878
1429
  mimeType?: string | null;
879
1430
  fileSize?: number | null;
880
1431
  kind?: string;
1432
+ /** @description Credit line set on the file in the media library (photographer or rights holder, for example "Jane Doe / Pexels"); filled automatically for stock photos. Show it where the license asks for attribution. null when there is none. */
1433
+ credit?: string | null;
1434
+ /**
1435
+ * Format: uri
1436
+ * @description Where the file came from (the stock photo's page, the original source); link the credit to it. null when there is none.
1437
+ */
1438
+ sourceUrl?: string | null;
881
1439
  };
882
1440
  /** @description One collection item. System collections add fields of their own at this level (blog: segments, toc, contentHtml, plaintext); GET /collections lists them in virtualFields. */
883
1441
  Item: {
884
1442
  id: string;
885
1443
  /** @description URL slug in the locale of the response */
886
1444
  slug: string;
887
- /** @description Path of this item's page on the site, in the locale of the response (`/blog/hello`, or `/en/blog/hello` for a secondary locale). It is the address Kanorio lists in the sitemap, site search and JSON-LD, so link to it instead of building the URL from the slug. Present for blog posts, for categories, tags and authors whose listing page is served (see `listings` on /site), and for items of a custom collection that has a `pathTemplate` (primary locale only). Absent when the item has no page of its own. */
1445
+ /** @description Path of this item's page on the site, in the locale of the response, with the locale prefix (`/blog/hello`, or `/en/blog/hello-en` for a secondary locale). It is the address Kanorio lists in the sitemap, site search and JSON-LD, so link to it instead of building the URL from the slug. Present for blog posts, for categories, tags and authors whose listing page is served (see `listings` on /site), and for items of a custom collection that has a `pathTemplate` (a secondary locale gets its prefix plus the same template, with that locale's slug). Absent when the item has no page of its own. */
888
1446
  path?: string;
889
1447
  publishedAt: string | null;
890
1448
  updatedAt: string;
891
1449
  fieldData: {
892
1450
  [key: string]: unknown;
893
1451
  };
894
- /** @description References named in `expand`, keyed by field id */
1452
+ /** @description Alt text written for an image where this item uses it, keyed by field id and then asset id: `imageAlt.cover[fieldData.cover]`, `imageAlt.photos[id]` for each gallery image. Use it instead of `assets[id].alt` when present; otherwise fall back to `assets[id].alt`. Lists only image and gallery fields that have one and that `fieldData` includes. The same text in every locale. */
1453
+ imageAlt: {
1454
+ [key: string]: {
1455
+ [key: string]: string;
1456
+ };
1457
+ };
1458
+ /** @description References named in `expand`, keyed by field id: `{ id, slug, title, fieldData, imageAlt }` (an array for a multi-reference field, null when the target is missing) */
895
1459
  expanded?: {
896
1460
  [key: string]: unknown;
897
1461
  };
@@ -904,7 +1468,7 @@ export interface components {
904
1468
  localeSlugs?: {
905
1469
  [key: string]: string;
906
1470
  };
907
- /** @description Multilingual sites, system collections: `path` in every live locale, for hreflang and a language switcher */
1471
+ /** @description Multilingual sites: this item's path in every live locale, keyed by locale code, without the locale prefix (each locale can have its own translated slug), like `localePaths` on pages and products. Present when `path` is. Use it for hreflang, a language switcher and sitemap alternates (`buildAlternates` and `seoMetadata` in @kanorio/sdk add the prefix). */
908
1472
  localePaths?: {
909
1473
  [key: string]: string;
910
1474
  };
@@ -1210,6 +1774,8 @@ export interface operations {
1210
1774
  query?: {
1211
1775
  /** @description Pass `preview=1` with `X-Kanorio-Preview: knr_pv_<token>` to check a preview token before entering preview mode: the token's signature, expiry and site are verified at the edge and an invalid token gets `401`. Site meta has no draft, so the body is the same as without it (`Cache-Control: no-store`). Used by `createPreviewRouteHandler` in `@kanorio/sdk/preview`. */
1212
1776
  preview?: "1";
1777
+ /** @description Locale for `name` and `description` (the translations of the brand display name and the site description). One of the site's live locales (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values return 400 UNSUPPORTED_LOCALE. Untranslated fields fall back to the primary locale, and `resolvedLocale` says which locale was served. `locales` is the same in every locale. */
1778
+ locale?: string;
1213
1779
  };
1214
1780
  header?: never;
1215
1781
  path?: never;
@@ -1265,7 +1831,7 @@ export interface operations {
1265
1831
  delivery_pages_list: {
1266
1832
  parameters: {
1267
1833
  query?: {
1268
- /** @description Locale for page titles and SEO fields. One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values, including locales that are still translating, return 400 UNSUPPORTED_LOCALE. Untranslated fields fall back to the primary locale. On multilingual sites each page carries resolvedLocale and availableLocales. Slugs stay in the primary locale's path space; prefix them with the locale's pathPrefix. */
1834
+ /** @description Locale for page titles and SEO fields. One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values return 400 UNSUPPORTED_LOCALE, and so do locales that are not live yet (still translating, or added without going live), except in preview: with a preview token they are accepted and their draft translations are returned. Untranslated fields fall back to the primary locale. On multilingual sites each page carries resolvedLocale and availableLocales. Slugs stay in the primary locale's path space; prefix them with the locale's pathPrefix. */
1269
1835
  locale?: string;
1270
1836
  /** @description Maximum number of items to return, 1-100. Defaults to 20. */
1271
1837
  limit?: number;
@@ -1302,7 +1868,7 @@ export interface operations {
1302
1868
  delivery_page_get: {
1303
1869
  parameters: {
1304
1870
  query?: {
1305
- /** @description Locale for the page title, SEO fields and section text. One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values, including locales that are still translating, return 400 UNSUPPORTED_LOCALE. Untranslated fields fall back to the primary locale. On multilingual sites the page carries resolvedLocale and availableLocales (use them for canonical and hreflang). Slugs and in-content links stay in the primary locale's path space; prefix them with the locale's pathPrefix. */
1871
+ /** @description Locale for the page title, SEO fields and section text. One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values return 400 UNSUPPORTED_LOCALE, and so do locales that are not live yet (still translating, or added without going live), except in preview: with a preview token they are accepted and their draft translations are returned. Untranslated fields fall back to the primary locale. On multilingual sites the page carries resolvedLocale and availableLocales (use them for canonical and hreflang). Slugs and in-content links stay in the primary locale's path space; prefix them with the locale's pathPrefix. */
1306
1872
  locale?: string;
1307
1873
  };
1308
1874
  header?: never;
@@ -1336,7 +1902,7 @@ export interface operations {
1336
1902
  delivery_globals_header_get: {
1337
1903
  parameters: {
1338
1904
  query?: {
1339
- /** @description Locale for the header text and the site settings copy (address, hours, copyright, buttons). One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values, including locales that are still translating, return 400 UNSUPPORTED_LOCALE. Untranslated fields fall back to the primary locale. */
1905
+ /** @description Locale for the header text and the site settings copy (address, hours, copyright, buttons). One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values return 400 UNSUPPORTED_LOCALE, and so do locales that are not live yet (still translating, or added without going live), except in preview: with a preview token they are accepted and their draft translations are returned. Untranslated fields fall back to the primary locale. */
1340
1906
  locale?: string;
1341
1907
  };
1342
1908
  header?: never;
@@ -1377,7 +1943,7 @@ export interface operations {
1377
1943
  delivery_globals_footer_get: {
1378
1944
  parameters: {
1379
1945
  query?: {
1380
- /** @description Locale for the footer text and the site settings copy (address, hours, copyright, buttons). One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values, including locales that are still translating, return 400 UNSUPPORTED_LOCALE. Untranslated fields fall back to the primary locale. */
1946
+ /** @description Locale for the footer text and the site settings copy (address, hours, copyright, buttons). One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values return 400 UNSUPPORTED_LOCALE, and so do locales that are not live yet (still translating, or added without going live), except in preview: with a preview token they are accepted and their draft translations are returned. Untranslated fields fall back to the primary locale. */
1381
1947
  locale?: string;
1382
1948
  };
1383
1949
  header?: never;
@@ -1466,7 +2032,7 @@ export interface operations {
1466
2032
  includeDepth?: 1;
1467
2033
  /** @description Comma-separated blog content formats: markdown, html, plaintext */
1468
2034
  formats?: string;
1469
- /** @description Locale for item fields marked localized; for the blog, blog_categories, blog_tags and authors collections, the post, category, tag and author translations (titles, excerpts, bodies, SEO fields). Expanded references are translated too. One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values, including locales that are still translating, return 400 UNSUPPORTED_LOCALE. Untranslated fields fall back to the primary locale. On multilingual sites each item carries resolvedLocale and availableLocales. */
2035
+ /** @description Locale for item fields marked localized; for the blog, blog_categories, blog_tags and authors collections, the post, category, tag and author translations (titles, excerpts, bodies, SEO fields). Expanded references are translated too. One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values return 400 UNSUPPORTED_LOCALE, and so do locales that are not live yet (still translating, or added without going live), except in preview: with a preview token they are accepted and their draft translations are returned. Untranslated fields fall back to the primary locale. On multilingual sites each item carries resolvedLocale and availableLocales. */
1470
2036
  locale?: string;
1471
2037
  /** @description Pass `preview=1` with `X-Kanorio-Preview: knr_pv_<token>` (or a server-held PAT with `collections:view`) to read unpublished draft `fieldData` (`Cache-Control: no-store`). */
1472
2038
  preview?: "1";
@@ -1504,7 +2070,7 @@ export interface operations {
1504
2070
  preview?: "1";
1505
2071
  /** @description Reference include depth. Only 1 is accepted in v1. */
1506
2072
  includeDepth?: 1;
1507
- /** @description Locale for the item, the same as the list endpoint (system collections use the post, category, tag and author translations; expanded references are translated too). One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values, including locales that are still translating, return 400 UNSUPPORTED_LOCALE. Untranslated fields fall back to the primary locale. On multilingual sites the item carries resolvedLocale and availableLocales. */
2073
+ /** @description Locale for the item, the same as the list endpoint (system collections use the post, category, tag and author translations; expanded references are translated too). One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values return 400 UNSUPPORTED_LOCALE, and so do locales that are not live yet (still translating, or added without going live), except in preview: with a preview token they are accepted and their draft translations are returned. Untranslated fields fall back to the primary locale. On multilingual sites the item carries resolvedLocale and availableLocales. */
1508
2074
  locale?: string;
1509
2075
  };
1510
2076
  header?: never;
@@ -1537,6 +2103,46 @@ export interface operations {
1537
2103
  503: components["responses"]["Error503"];
1538
2104
  };
1539
2105
  };
2106
+ delivery_collection_singleton: {
2107
+ parameters: {
2108
+ query?: {
2109
+ fields?: string;
2110
+ expand?: string;
2111
+ preview?: "1";
2112
+ /** @description Reference include depth. Only 1 is accepted in v1. */
2113
+ includeDepth?: 1;
2114
+ /** @description Locale for the item, the same as GET /collections/{key}/items/{slug}. Omit it for the primary locale. */
2115
+ locale?: string;
2116
+ };
2117
+ header?: never;
2118
+ path: {
2119
+ key: string;
2120
+ };
2121
+ cookie?: never;
2122
+ };
2123
+ requestBody?: never;
2124
+ responses: {
2125
+ /** @description OK */
2126
+ 200: {
2127
+ headers: {
2128
+ [name: string]: unknown;
2129
+ };
2130
+ content: {
2131
+ "application/json": {
2132
+ item: components["schemas"]["Item"];
2133
+ assets: {
2134
+ [key: string]: components["schemas"]["Asset"];
2135
+ };
2136
+ access?: components["schemas"]["AccessSummary"];
2137
+ };
2138
+ };
2139
+ };
2140
+ 400: components["responses"]["Error400"];
2141
+ 404: components["responses"]["Error404"];
2142
+ 429: components["responses"]["Error429"];
2143
+ 503: components["responses"]["Error503"];
2144
+ };
2145
+ };
1540
2146
  delivery_blog_feed_rss: {
1541
2147
  parameters: {
1542
2148
  query?: {
@@ -1885,8 +2491,10 @@ export interface operations {
1885
2491
  delivery_form_get: {
1886
2492
  parameters: {
1887
2493
  query?: {
1888
- /** @description Locale for the form name, description, question labels, hints, choice labels, submit button and success message. One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values, including locales that are still translating, return 400 UNSUPPORTED_LOCALE. Untranslated fields fall back to the primary locale. Field and choice ids are locale-independent, so submissions are unaffected. */
2494
+ /** @description Locale for the form name, description, question labels, hints, choice labels, submit button and success message. One of the site's locales from /site (a code such as `en-US` or the URL prefix such as `en`); omit it for the primary locale. Other values return 400 UNSUPPORTED_LOCALE, and so do locales that are not live yet (still translating, or added without going live), except in preview: with a preview token (or a server-held PAT with `collections:view`) they are accepted and their draft translations are returned. A preview request for a locale that is not live is checked for its token first: without one it gets 401, whether or not the site has that locale. Untranslated fields fall back to the primary locale. Field and choice ids are locale-independent, so submissions are unaffected. */
1889
2495
  locale?: string;
2496
+ /** @description Pass `preview=1` with `X-Kanorio-Preview: knr_pv_<token>` (or a server-held PAT with `collections:view`) to read the form in a locale that is not live yet, with its draft translations (`Cache-Control: no-store`). Forms have no drafts of their own, so only such a locale makes a preview request: without `locale`, or with a live one, the response is the same cached one as without `preview` and no token is checked. */
2497
+ preview?: "1";
1890
2498
  };
1891
2499
  header?: never;
1892
2500
  path: {
@@ -1903,9 +2511,7 @@ export interface operations {
1903
2511
  };
1904
2512
  content: {
1905
2513
  "application/json": {
1906
- form: {
1907
- [key: string]: unknown;
1908
- };
2514
+ form: components["schemas"]["Form"];
1909
2515
  };
1910
2516
  };
1911
2517
  };
@@ -2144,10 +2750,13 @@ export interface operations {
2144
2750
  * @enum {string}
2145
2751
  */
2146
2752
  consent?: "checked" | "submit_statement";
2147
- /** @description Id of the consent text the visitor saw (from GET /forms/{id}). */
2753
+ /** @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
2754
  consentTextId?: string;
2755
+ /** @description The visitor's language, such as the browser's (navigator.language). Kept on the submission and the contact; it does not decide the redirect. */
2149
2756
  locale?: string;
2150
- /** @description Path of the page the form was on, for the submission record. */
2757
+ /** @description The site locale of the page the form was on (a code from /site locales[] or its URL prefix). A redirect to a path on the site gets this locale's URL prefix. Without it, or when it is not a live locale, the locale is read from pagePath. */
2758
+ pageLocale?: string;
2759
+ /** @description Path of the page the form was on, for the submission record. Also decides the redirect's locale prefix when pageLocale is not sent. */
2151
2760
  pagePath?: string;
2152
2761
  /** @description Honeypot. Send an empty string; any value marks the request as automated. */
2153
2762
  _hp?: string;
@@ -2174,8 +2783,15 @@ export interface operations {
2174
2783
  };
2175
2784
  content: {
2176
2785
  "application/json": {
2177
- /** @enum {string} */
2786
+ /**
2787
+ * @description Present when the form did not take the submission because of its own state. Nothing was saved.
2788
+ * @enum {string}
2789
+ */
2178
2790
  state?: "closed" | "not_open" | "full";
2791
+ /** @description Id of this submission. Absent when state is present. */
2792
+ submissionId?: string;
2793
+ /** @description Where to send the visitor now, when the form has a redirect after submit: a path on the site (with the URL prefix of pageLocale, or of the page the form was on, read from pagePath, when pageLocale was not sent) 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. */
2794
+ redirectUrl?: string;
2179
2795
  };
2180
2796
  };
2181
2797
  };