@roottale/cms-client 0.63.0 → 0.64.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @roottale/cms-client
 
+## 0.64.0
+
+### Minor Changes
+
+- 5ccf503: 한 사이트의 여러 문의 폼을 발행 버전별로 연결할 수 있도록 공통 폼 정의·검증 계약과 `fetchInquiryForm`·`submitFormInquiry` 서버 SDK를 추가합니다. 구조화 답변·동의·중복 재시도·접수증과 같은 사이트의 견적/AS 폼 연동 예제를 제공합니다. 기존 문의 SDK는 유지합니다.
+
+### Patch Changes
+
+- Updated dependencies [5ccf503]
+  - @roottale/inquiry-forms@0.2.0
+
 ## 0.63.0
 
 ## 0.62.0

package/dist/server.d.ts

@@ -1,3 +1,5 @@
+import { InquiryFormDefinition, InquiryAnswer } from '@roottale/inquiry-forms';
+export { InquiryAnswer, InquiryFormDefinition, InquiryFormField, InquiryKind } from '@roottale/inquiry-forms';
 import { InquiryAttribution } from './attribution.js';
 export { parseAttributionJson } from './attribution.js';
 
@@ -1162,6 +1164,71 @@ declare function fetchSiteInquiries(options: FetchSiteInquiriesOptions): Promise
 declare function fetchSiteInquiry(options: FetchSiteInquiryOptions): Promise<SiteInquiryDetail | null>;
 declare function submitSiteInquiry(options: SubmitSiteInquiryOptions): Promise<SubmitSiteInquiryResult>;
 
+/** A published form belongs to exactly one site. Versions are immutable. */
+interface PublishedInquiryForm {
+    formId: string;
+    siteId: string;
+    formKey: string;
+    version: number;
+    definition: InquiryFormDefinition;
+}
+interface FetchInquiryFormOptions {
+    apiKey: string;
+    baseUrl?: string;
+    /** Required for a tenant-wide key; a site-bound key already identifies its site. */
+    siteId?: string;
+    formId: string;
+    signal?: AbortSignal;
+}
+interface SubmitFormInquiryFields {
+    siteId?: string;
+    /** Version that the visitor saw, including its consent notice. */
+    version: number;
+    answers: Record<string, InquiryAnswer>;
+    privacyConsent: boolean;
+    /** Caller-generated key. Reuse the same key and payload after an uncertain response. */
+    idempotencyKey: string;
+    placement?: string;
+    turnstileToken?: string;
+    attribution?: InquiryAttribution | null;
+    /** readJourney() array; the API validates entries and enforces the site's privacy mode. */
+    journey?: readonly unknown[];
+}
+interface SubmitFormInquiryOptions {
+    apiKey: string;
+    baseUrl?: string;
+    formId: string;
+    fields: SubmitFormInquiryFields;
+    signal?: AbortSignal;
+}
+interface FormInquiryReceipt {
+    id: string;
+    inquiryNo: number;
+    receivedAt: string;
+    /** True when this is the receipt of an already saved submission. */
+    replayed: boolean;
+}
+type SubmitFormInquiryResult = {
+    ok: true;
+    receipt: FormInquiryReceipt;
+} | {
+    ok: false;
+    /** Transport/invalid_response can mean the server saved the inquiry before the response was lost. */
+    kind: "api" | "transport" | "invalid_response";
+    code: string;
+    status: number | null;
+    message: string;
+    fieldErrors: Record<string, string[]>;
+    formErrors: string[];
+};
+/** Server-only. Always reads the current published form; 404 returns null. */
+declare function fetchInquiryForm(options: FetchInquiryFormOptions): Promise<PublishedInquiryForm | null>;
+/**
+ * Server-only JSON intake. A successful HTTP status is insufficient without a valid receipt.
+ * Does not retry or generate keys; the caller keeps its key until the receipt is confirmed.
+ */
+declare function submitFormInquiry(options: SubmitFormInquiryOptions): Promise<SubmitFormInquiryResult>;
+
 /**
  * 글 미리보기 — 어드민 편집기가 발급한 토큰으로 초안을 **발행 글과 같은 모양**으로
  * 받아 온다. 고객 사이트는 글 상세 템플릿을 그대로 재사용해 미리보기를 그리면
@@ -1564,4 +1631,4 @@ declare function formatKoreanPhoneNumber(input: string): string;
  */
 declare function submitInquiry(options: SubmitInquiryOptions): Promise<SubmitInquiryResult>;
 
-export { type ActionDockAction, type ActionDockKind, type ActionDockPosition, type ActionDockSettings, type AnalyticsTagConfig, type AnalyticsTagProvider, type AnnouncementItem, type AnnouncementSettings, type AnnouncementTone, type AnnouncementVariant, type ArticleSchemaInput, BLOG_SETTINGS_CACHE_TAG, BUSINESS_CACHE_TAG, type BusinessDayCode, type BusinessOpeningHours, type BusinessType, CMS_CLIENT_VERSION, COLLECTIONS_CACHE_TAG, CmsApiError, type CmsArchiveRelatedGroup, type CmsArchiveRelatedPost, type CmsCategoryCount, type CmsCategoryCounts, type CmsContentModel, type CmsExposureCampaign, type CmsExposureDecision, type CmsFieldMetaEntry, type CmsPostContent, type CmsPostContentPage, type CmsPostPreviewContent, type CmsPostPreviewInfo, type CmsPostTranslationRef, type CmsPostType, type CmsRouteCollection, type CmsSearchHit, type CmsSitePattern, type CmsSitePatternPresentation, type CmsTaxonomyKind, type CmsTermRef, DEFAULT_BLOG_SETTINGS, DEFAULT_SITE_PATTERN_PRESENTATION, EXPOSURE_CACHE_TAG, type FetchAnalyticsOptions, type FetchAuthorsOptions, type FetchBlogSettingsOptions, type FetchBusinessProfileOptions, type FetchCategoryCountsOptions, type FetchCollectionsOptions, type FetchContentModelsOptions, type FetchExposureDecisionOptions, type FetchExposureOptions, type FetchMenuOptions, type FetchMenusOptions, type FetchPageBySlugOptions, type FetchPostOptions, type FetchPostPreviewOptions, type FetchPostsOptions, type FetchRedirectsOptions, type FetchSiteInquiriesOptions, type FetchSiteInquiryOptions, type FetchSitePatternsOptions, type FetchThemeOptions, INQUIRY_ERROR_MESSAGES, InquiryAttribution, type InquiryBoardSettings, type InquiryVertical, LOCAL_BUSINESS_MAX_SERVICES, LOCAL_BUSINESS_SERVICE_MAX_LENGTH, type LocalBusinessProfileInput, MENUS_CACHE_TAG, POST_FOOTER_PATTERN_SLOT, type ResolvedPostDisplay, type RootTaleAuthor, type RootTaleBlogPostCta, type RootTaleBlogSettings, type RootTaleBusinessProfile, type RootTaleMenu, type RootTaleMenuItem, type RootTaleRedirect, type RootTaleSiteProfile, type RootTaleSitemapSettings, type RootTaleTheme, type RssFeedInput, type RssItemInput, SETTINGS_CACHE_TAGS, SITE_PATTERNS_CACHE_TAG, type SearchPostsOptions, type SiteAnalyticsTags, type SiteInquiryDetail, type SiteInquiryListItem, type SiteInquiryListPage, type SiteInquiryStatus, type SiteNavColumn, type SiteNavCta, type SiteNavGroup, type SiteNavLink, type SiteNavSettings, type SubmitInquiryFields, type SubmitInquiryOptions, type SubmitInquiryResult, type SubmitSiteInquiryFields, type SubmitSiteInquiryOptions, type SubmitSiteInquiryResult, THEME_CACHE_TAG, articleSchema, breadcrumbSchema, businessProfileFromWire, collectionPageSchema, contentIdMeta, faqSchema, fetchAnalyticsConfig, fetchAuthors, fetchBlogSettings, fetchBusinessProfile, fetchCategoryCounts, fetchCollections, fetchCollectionsSafeDefault, fetchContentModels, fetchExposure, fetchExposureDecision, fetchMenu, fetchMenus, fetchPageBySlug, fetchPost, fetchPostPreview, fetchPosts, fetchRedirects, fetchSiteInquiries, fetchSiteInquiry, fetchSitePatterns, fetchTheme, formatKoreanPhoneNumber, generateRssXml, inquiryErrorMessage, isPreviewExpiredError, jsonLdJson, jsonLdScript, localBusinessSchema, organizationSchema, parseInquiryRedirect, profilePageSchema, resolvePostDisplay, resolveSearchHitPath, rssItemsFromPosts, searchPosts, selectRelatedPosts, selectSitePatternForSlot, sitePatternPresentationAttributes, submitInquiry, submitSiteInquiry, websiteSchema };
+export { type ActionDockAction, type ActionDockKind, type ActionDockPosition, type ActionDockSettings, type AnalyticsTagConfig, type AnalyticsTagProvider, type AnnouncementItem, type AnnouncementSettings, type AnnouncementTone, type AnnouncementVariant, type ArticleSchemaInput, BLOG_SETTINGS_CACHE_TAG, BUSINESS_CACHE_TAG, type BusinessDayCode, type BusinessOpeningHours, type BusinessType, CMS_CLIENT_VERSION, COLLECTIONS_CACHE_TAG, CmsApiError, type CmsArchiveRelatedGroup, type CmsArchiveRelatedPost, type CmsCategoryCount, type CmsCategoryCounts, type CmsContentModel, type CmsExposureCampaign, type CmsExposureDecision, type CmsFieldMetaEntry, type CmsPostContent, type CmsPostContentPage, type CmsPostPreviewContent, type CmsPostPreviewInfo, type CmsPostTranslationRef, type CmsPostType, type CmsRouteCollection, type CmsSearchHit, type CmsSitePattern, type CmsSitePatternPresentation, type CmsTaxonomyKind, type CmsTermRef, DEFAULT_BLOG_SETTINGS, DEFAULT_SITE_PATTERN_PRESENTATION, EXPOSURE_CACHE_TAG, type FetchAnalyticsOptions, type FetchAuthorsOptions, type FetchBlogSettingsOptions, type FetchBusinessProfileOptions, type FetchCategoryCountsOptions, type FetchCollectionsOptions, type FetchContentModelsOptions, type FetchExposureDecisionOptions, type FetchExposureOptions, type FetchInquiryFormOptions, type FetchMenuOptions, type FetchMenusOptions, type FetchPageBySlugOptions, type FetchPostOptions, type FetchPostPreviewOptions, type FetchPostsOptions, type FetchRedirectsOptions, type FetchSiteInquiriesOptions, type FetchSiteInquiryOptions, type FetchSitePatternsOptions, type FetchThemeOptions, type FormInquiryReceipt, INQUIRY_ERROR_MESSAGES, InquiryAttribution, type InquiryBoardSettings, type InquiryVertical, LOCAL_BUSINESS_MAX_SERVICES, LOCAL_BUSINESS_SERVICE_MAX_LENGTH, type LocalBusinessProfileInput, MENUS_CACHE_TAG, POST_FOOTER_PATTERN_SLOT, type PublishedInquiryForm, type ResolvedPostDisplay, type RootTaleAuthor, type RootTaleBlogPostCta, type RootTaleBlogSettings, type RootTaleBusinessProfile, type RootTaleMenu, type RootTaleMenuItem, type RootTaleRedirect, type RootTaleSiteProfile, type RootTaleSitemapSettings, type RootTaleTheme, type RssFeedInput, type RssItemInput, SETTINGS_CACHE_TAGS, SITE_PATTERNS_CACHE_TAG, type SearchPostsOptions, type SiteAnalyticsTags, type SiteInquiryDetail, type SiteInquiryListItem, type SiteInquiryListPage, type SiteInquiryStatus, type SiteNavColumn, type SiteNavCta, type SiteNavGroup, type SiteNavLink, type SiteNavSettings, type SubmitFormInquiryFields, type SubmitFormInquiryOptions, type SubmitFormInquiryResult, type SubmitInquiryFields, type SubmitInquiryOptions, type SubmitInquiryResult, type SubmitSiteInquiryFields, type SubmitSiteInquiryOptions, type SubmitSiteInquiryResult, THEME_CACHE_TAG, articleSchema, breadcrumbSchema, businessProfileFromWire, collectionPageSchema, contentIdMeta, faqSchema, fetchAnalyticsConfig, fetchAuthors, fetchBlogSettings, fetchBusinessProfile, fetchCategoryCounts, fetchCollections, fetchCollectionsSafeDefault, fetchContentModels, fetchExposure, fetchExposureDecision, fetchInquiryForm, fetchMenu, fetchMenus, fetchPageBySlug, fetchPost, fetchPostPreview, fetchPosts, fetchRedirects, fetchSiteInquiries, fetchSiteInquiry, fetchSitePatterns, fetchTheme, formatKoreanPhoneNumber, generateRssXml, inquiryErrorMessage, isPreviewExpiredError, jsonLdJson, jsonLdScript, localBusinessSchema, organizationSchema, parseInquiryRedirect, profilePageSchema, resolvePostDisplay, resolveSearchHitPath, rssItemsFromPosts, searchPosts, selectRelatedPosts, selectSitePatternForSlot, sitePatternPresentationAttributes, submitFormInquiry, submitInquiry, submitSiteInquiry, websiteSchema };

package/dist/server.js

@@ -4,7 +4,7 @@ import {
 
 // src/server-base.ts
 var DEFAULT_BASE_URL = "https://api.roottale.com";
-var CLIENT_VERSION = true ? "0.63.0" : "dev";
+var CLIENT_VERSION = true ? "0.64.0" : "dev";
 var CMS_CLIENT_VERSION = CLIENT_VERSION;
 function authHeaders(apiKey) {
   return {
@@ -953,6 +953,137 @@ function fromDetailWire(item) {
   };
 }
 
+// src/server-inquiry-forms.ts
+import { inquiryFormDefinitionSchema } from "@roottale/inquiry-forms";
+async function fetchInquiryForm(options) {
+  assertServer();
+  const params = new URLSearchParams();
+  if (options.siteId) params.set("site_id", options.siteId);
+  const query = params.toString();
+  const response = await fetch(`${formUrl(options)}${query ? `?${query}` : ""}`, {
+    headers: authHeaders(options.apiKey),
+    cache: "no-store",
+    redirect: "manual",
+    signal: options.signal
+  });
+  if (response.status === 404) return null;
+  if (!response.ok) throw await toApiError(response);
+  const body = await readJson(response);
+  if (!isRecord(body) || body.form_id !== options.formId || !isId(body.site_id) || options.siteId !== void 0 && body.site_id !== options.siteId || !isNonEmptyString(body.form_key) || !isPositiveInteger(body.version)) {
+    throw invalidFormResponse(response.status);
+  }
+  const definition = inquiryFormDefinitionSchema.safeParse(body.definition);
+  if (!definition.success) throw invalidFormResponse(response.status);
+  return {
+    formId: options.formId,
+    siteId: body.site_id,
+    formKey: body.form_key,
+    version: body.version,
+    definition: definition.data
+  };
+}
+async function submitFormInquiry(options) {
+  assertServer();
+  const fields = options.fields;
+  let response;
+  try {
+    response = await fetch(`${formUrl(options)}/submissions`, {
+      method: "POST",
+      headers: { ...authHeaders(options.apiKey), "content-type": "application/json" },
+      body: JSON.stringify({
+        site_id: fields.siteId,
+        version: fields.version,
+        answers: fields.answers,
+        privacy_consent: fields.privacyConsent,
+        idempotency_key: fields.idempotencyKey,
+        placement: fields.placement,
+        turnstile_token: fields.turnstileToken,
+        attribution: fields.attribution ?? void 0,
+        journey: fields.journey
+      }),
+      cache: "no-store",
+      redirect: "manual",
+      signal: options.signal
+    });
+  } catch {
+    return failure(
+      "transport",
+      "network_error",
+      null,
+      "\uC811\uC218 \uACB0\uACFC\uB97C \uD655\uC778\uD558\uC9C0 \uBABB\uD588\uC2B5\uB2C8\uB2E4. \uAC19\uC740 \uB0B4\uC6A9\uC73C\uB85C \uB2E4\uC2DC \uC2DC\uB3C4\uD574\uC8FC\uC138\uC694."
+    );
+  }
+  const body = await readJson(response);
+  if (!response.ok) {
+    const code = isRecord(body) && isNonEmptyString(body.code) ? body.code : codeForStatus(response.status);
+    const message = isRecord(body) && isNonEmptyString(body.message) ? body.message : "\uBB38\uC758 \uC804\uC1A1\uC5D0 \uC2E4\uD328\uD588\uC2B5\uB2C8\uB2E4. \uC785\uB825 \uB0B4\uC6A9\uACFC \uC5F0\uACB0 \uC0C1\uD0DC\uB97C \uD655\uC778\uD574\uC8FC\uC138\uC694.";
+    const details = isRecord(body) && isRecord(body.details) ? body.details : void 0;
+    return {
+      ...failure("api", code, response.status, message),
+      fieldErrors: parseFieldErrors(details?.field_errors),
+      formErrors: stringArray(details?.form_errors)
+    };
+  }
+  if (!isRecord(body) || !isId(body.id) || !isPositiveInteger(body.inquiry_no) || !isTimestamp(body.received_at) || typeof body.replayed !== "boolean") {
+    return failure(
+      "invalid_response",
+      "invalid_response",
+      response.status,
+      "\uC811\uC218\uC99D\uC744 \uD655\uC778\uD558\uC9C0 \uBABB\uD588\uC2B5\uB2C8\uB2E4. \uAC19\uC740 \uB0B4\uC6A9\uC73C\uB85C \uB2E4\uC2DC \uC2DC\uB3C4\uD574\uC8FC\uC138\uC694."
+    );
+  }
+  return {
+    ok: true,
+    receipt: { id: body.id, inquiryNo: body.inquiry_no, receivedAt: body.received_at, replayed: body.replayed }
+  };
+}
+function formUrl(options) {
+  const base = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  return `${base}/v1/public/inquiry-forms/${encodeURIComponent(options.formId)}`;
+}
+function failure(kind, code, status, message) {
+  return { ok: false, kind, code, status, message, fieldErrors: {}, formErrors: [] };
+}
+function invalidFormResponse(status) {
+  return new CmsApiError("RootTale inquiry form response is invalid", status, "invalid_response");
+}
+async function readJson(response) {
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function isId(value) {
+  return typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value);
+}
+function isPositiveInteger(value) {
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
+}
+function isTimestamp(value) {
+  return typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(value) && Number.isFinite(Date.parse(value));
+}
+function stringArray(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function parseFieldErrors(value) {
+  if (!isRecord(value)) return {};
+  return Object.fromEntries(Object.entries(value).map(([key, errors]) => [key, stringArray(errors)]));
+}
+function codeForStatus(status) {
+  if (status === 401) return "invalid_api_key";
+  if (status === 403) return "insufficient_scope";
+  if (status === 404) return "not_found";
+  if (status === 429) return "rate_limited";
+  return "request_failed";
+}
+
 // src/server-preview.ts
 function isPreviewExpiredError(error) {
   return error instanceof CmsApiError && (error.code === "preview_expired" || error.status === 410);
@@ -1523,6 +1654,7 @@ export {
   fetchContentModels,
   fetchExposure,
   fetchExposureDecision,
+  fetchInquiryForm,
   fetchMenu,
   fetchMenus,
   fetchPageBySlug,
@@ -1552,6 +1684,7 @@ export {
   selectRelatedPosts,
   selectSitePatternForSlot,
   sitePatternPresentationAttributes,
+  submitFormInquiry,
   submitInquiry,
   submitSiteInquiry,
   websiteSchema