@distinctagency/cms-client 1.23.0 → 1.25.0

package/dist/index.d.mts

@@ -7,7 +7,7 @@ import { SupabaseClient } from '@supabase/supabase-js';
  * report installed-version telemetry and to send `x-cms-client-version` on
  * outgoing requests.
  */
-declare const CMS_CLIENT_VERSION = "1.23.0";
+declare const CMS_CLIENT_VERSION = "1.25.0";
 
 /** Field types supported by the CMS schema */
 type FieldType = "text" | "textarea" | "richtext" | "date" | "datetime" | "select" | "number" | "boolean" | "image" | "gallery" | "url" | "file" | "reference" | "multi-reference" | "computed" | "color" | "tags" | "json" | "embed" | "flipbook";
@@ -58,6 +58,10 @@ interface FieldDefinition {
     decimal_places?: number;
     /** For date fields: which parts of the date the editor collects. Defaults to `full`. Stored in partial-ISO form — see {@link DateGranularity}. */
     date_granularity?: DateGranularity;
+    /** For text/textarea/richtext fields: hard maximum character count. Enforced in the editor and on save. Undefined = no cap. */
+    max_length?: number;
+    /** For text/textarea/richtext fields: soft target character count. Exceeding it shows a warning but does not block saving. */
+    recommended_length?: number;
 }
 interface Tenant {
     id: string;
@@ -111,6 +115,10 @@ interface ContentType {
     schema: FieldDefinition[];
     seo_config?: ContentTypeSeoConfig | null;
     required_membership_tier_id?: string | null;
+    /** When true, this content type is a "page": it holds exactly one item, edited as a singleton document rather than a collection. */
+    is_singleton?: boolean;
+    /** For singleton pages: the site path the visual editor previews (e.g. "/", "/about"). Defaults to "/". */
+    preview_path?: string;
     created_at: string;
 }
 interface ContentItem {
@@ -419,6 +427,18 @@ declare function createCmsClient(supabase: SupabaseClient, options: CmsClientOpt
      * Returns null if not found.
      */
     getContentItemBySlug(contentTypeSlug: string, itemSlug: string): Promise<ContentItem | null>;
+    /**
+     * Get the single published item for a singleton content type ("page").
+     *
+     * A singleton content type owns exactly one item. Use this for editable
+     * page copy (hero text, section headings, etc.) stored in the CMS.
+     * Returns null when the singleton has no published item yet — callers
+     * should fall back to their hardcoded defaults in that case.
+     *
+     * Wrap this in `unstable_cache` with a `cms:singleton:<slug>` tag on the
+     * consuming site to cache it and revalidate via the CMS webhook.
+     */
+    getSingleton(contentTypeSlug: string): Promise<ContentItem | null>;
     /**
      * Get a content type definition (including its field schema).
      */
@@ -527,6 +547,13 @@ interface TrackingConfigOptions {
  * handler so public-token changes take effect immediately.
  */
 declare const MAPBOX_CONFIG_TAG = "cms:mapbox-config";
+/**
+ * Cache tag for a singleton "page" content type. Wrap `getSingleton(slug)` in
+ * `unstable_cache` tagged with `singletonTag(slug)`, then call
+ * `revalidateTag(singletonTag(slug))` from the CMS `content.updated` webhook
+ * (the webhook payload's `cache_tags` already include this value).
+ */
+declare function singletonTag(slug: string): string;
 interface MapboxConfigOptions {
     /** Cache lifetime in seconds on Next.js. Defaults to 3600. `0` disables caching, `false` caches until tag revalidation. Ignored outside Next.js. */
     revalidate?: number | false;
@@ -908,4 +935,57 @@ declare function revalidateAllTags(payload: Pick<WebhookEventPayload, "cache_tag
     expire?: number;
 }) => unknown): string[];
 
-export { type BookingStatus, CMS_CLIENT_VERSION, type CmsClientOptions, type CmsEvent, type CmsTicketTier, type ContentItem, type ContentQueryOptions, type ContentType, type ContentTypeSeoConfig, type CreateBookingParams, type CreateBookingResult, type CreateOrderParams, type CreateOrderResult, type DateGranularity, type DiscountType, type EmbedValue, type EventQueryOptions, type EventStatus, type EventWithTiers, type FieldDefinition, type FieldType, type FlipbookPagePublic, type FlipbookPublic, type FlipbookTocEntryPublic, type FormatPartialDateOptions, type GeocodeOptions, type GeocodeResult, type GoogleReview, IMAGE_PRESETS, type ImageConfig, type ImageTransformOptions, MAPBOX_CONFIG_TAG, type MapboxConfig, type MapboxConfigOptions, type MapsClientOptions, type MediaFolder, type MediaItem, type Member, type MembershipTier, type OrderAddress, type OrderLineItem, type OrderStatus, type ParsedPartialDate, type PaymentStatus, type Product, type ProductCategory, type ProductOption, type ProductQueryOptions, type ProductStatus, type ProductVariant, type Profile, type ReviewQueryOptions, TRACKING_CONFIG_TAG, type Tenant, type TenantMembership, type TrackingConfig, type TrackingConfigOptions, WEBHOOK_EVENTS, type WebhookEvent, type WebhookEventPayload, createCmsClient, createEventsClient, createMapsClient, createShopClient, formatPartialDate, getEmbedHtml, getSrcSet, getTransformUrl, parsePartialDate, revalidateAllTags, verifyWebhookSignature };
+/** Discriminator stamped on every visual-editing postMessage. */
+declare const CMS_VISUAL_SOURCE: "cms-visual";
+/** CMS origins the bridge will trust by default. */
+declare const DEFAULT_TRUSTED_ORIGINS: readonly string[];
+type VisualFieldType = "text" | "image";
+/** Compact wire type announced in `ready`; the schema adds length constraints. */
+interface VisualFieldMeta {
+    name: string;
+    type: VisualFieldType;
+}
+interface VisualFieldSchema {
+    name: string;
+    type: VisualFieldType;
+    max_length?: number;
+    recommended_length?: number;
+}
+interface ReadyMessage {
+    source: typeof CMS_VISUAL_SOURCE;
+    type: "ready";
+    fields: VisualFieldMeta[];
+}
+interface EditMessage {
+    source: typeof CMS_VISUAL_SOURCE;
+    type: "edit";
+    name: string;
+    value: string;
+    length: number;
+}
+interface PickImageMessage {
+    source: typeof CMS_VISUAL_SOURCE;
+    type: "pick-image";
+    name: string;
+}
+interface InitMessage {
+    source: typeof CMS_VISUAL_SOURCE;
+    type: "init";
+    values: Record<string, string>;
+    schema: Record<string, VisualFieldSchema>;
+}
+interface SetMessage {
+    source: typeof CMS_VISUAL_SOURCE;
+    type: "set";
+    name: string;
+    value: string;
+}
+type BridgeOutbound = ReadyMessage | EditMessage | PickImageMessage;
+type BridgeInbound = InitMessage | SetMessage;
+type VisualMessage = BridgeOutbound | BridgeInbound;
+/** Exact-match origin allowlist, plus any localhost port for local dev. */
+declare function isTrustedOrigin(origin: string, allowlist: readonly string[]): boolean;
+/** Narrow an unknown postMessage payload to a visual message, or null. */
+declare function parseVisualMessage(data: unknown): VisualMessage | null;
+
+export { type BookingStatus, type BridgeInbound, type BridgeOutbound, CMS_CLIENT_VERSION, CMS_VISUAL_SOURCE, type CmsClientOptions, type CmsEvent, type CmsTicketTier, type ContentItem, type ContentQueryOptions, type ContentType, type ContentTypeSeoConfig, type CreateBookingParams, type CreateBookingResult, type CreateOrderParams, type CreateOrderResult, DEFAULT_TRUSTED_ORIGINS, type DateGranularity, type DiscountType, type EditMessage, type EmbedValue, type EventQueryOptions, type EventStatus, type EventWithTiers, type FieldDefinition, type FieldType, type FlipbookPagePublic, type FlipbookPublic, type FlipbookTocEntryPublic, type FormatPartialDateOptions, type GeocodeOptions, type GeocodeResult, type GoogleReview, IMAGE_PRESETS, type ImageConfig, type ImageTransformOptions, type InitMessage, MAPBOX_CONFIG_TAG, type MapboxConfig, type MapboxConfigOptions, type MapsClientOptions, type MediaFolder, type MediaItem, type Member, type MembershipTier, type OrderAddress, type OrderLineItem, type OrderStatus, type ParsedPartialDate, type PaymentStatus, type PickImageMessage, type Product, type ProductCategory, type ProductOption, type ProductQueryOptions, type ProductStatus, type ProductVariant, type Profile, type ReadyMessage, type ReviewQueryOptions, type SetMessage, TRACKING_CONFIG_TAG, type Tenant, type TenantMembership, type TrackingConfig, type TrackingConfigOptions, type VisualFieldMeta, type VisualFieldSchema, type VisualFieldType, type VisualMessage, WEBHOOK_EVENTS, type WebhookEvent, type WebhookEventPayload, createCmsClient, createEventsClient, createMapsClient, createShopClient, formatPartialDate, getEmbedHtml, getSrcSet, getTransformUrl, isTrustedOrigin, parsePartialDate, parseVisualMessage, revalidateAllTags, singletonTag, verifyWebhookSignature };

package/dist/index.d.ts

@@ -7,7 +7,7 @@ import { SupabaseClient } from '@supabase/supabase-js';
  * report installed-version telemetry and to send `x-cms-client-version` on
  * outgoing requests.
  */
-declare const CMS_CLIENT_VERSION = "1.23.0";
+declare const CMS_CLIENT_VERSION = "1.25.0";
 
 /** Field types supported by the CMS schema */
 type FieldType = "text" | "textarea" | "richtext" | "date" | "datetime" | "select" | "number" | "boolean" | "image" | "gallery" | "url" | "file" | "reference" | "multi-reference" | "computed" | "color" | "tags" | "json" | "embed" | "flipbook";
@@ -58,6 +58,10 @@ interface FieldDefinition {
     decimal_places?: number;
     /** For date fields: which parts of the date the editor collects. Defaults to `full`. Stored in partial-ISO form — see {@link DateGranularity}. */
     date_granularity?: DateGranularity;
+    /** For text/textarea/richtext fields: hard maximum character count. Enforced in the editor and on save. Undefined = no cap. */
+    max_length?: number;
+    /** For text/textarea/richtext fields: soft target character count. Exceeding it shows a warning but does not block saving. */
+    recommended_length?: number;
 }
 interface Tenant {
     id: string;
@@ -111,6 +115,10 @@ interface ContentType {
     schema: FieldDefinition[];
     seo_config?: ContentTypeSeoConfig | null;
     required_membership_tier_id?: string | null;
+    /** When true, this content type is a "page": it holds exactly one item, edited as a singleton document rather than a collection. */
+    is_singleton?: boolean;
+    /** For singleton pages: the site path the visual editor previews (e.g. "/", "/about"). Defaults to "/". */
+    preview_path?: string;
     created_at: string;
 }
 interface ContentItem {
@@ -419,6 +427,18 @@ declare function createCmsClient(supabase: SupabaseClient, options: CmsClientOpt
      * Returns null if not found.
      */
     getContentItemBySlug(contentTypeSlug: string, itemSlug: string): Promise<ContentItem | null>;
+    /**
+     * Get the single published item for a singleton content type ("page").
+     *
+     * A singleton content type owns exactly one item. Use this for editable
+     * page copy (hero text, section headings, etc.) stored in the CMS.
+     * Returns null when the singleton has no published item yet — callers
+     * should fall back to their hardcoded defaults in that case.
+     *
+     * Wrap this in `unstable_cache` with a `cms:singleton:<slug>` tag on the
+     * consuming site to cache it and revalidate via the CMS webhook.
+     */
+    getSingleton(contentTypeSlug: string): Promise<ContentItem | null>;
     /**
      * Get a content type definition (including its field schema).
      */
@@ -527,6 +547,13 @@ interface TrackingConfigOptions {
  * handler so public-token changes take effect immediately.
  */
 declare const MAPBOX_CONFIG_TAG = "cms:mapbox-config";
+/**
+ * Cache tag for a singleton "page" content type. Wrap `getSingleton(slug)` in
+ * `unstable_cache` tagged with `singletonTag(slug)`, then call
+ * `revalidateTag(singletonTag(slug))` from the CMS `content.updated` webhook
+ * (the webhook payload's `cache_tags` already include this value).
+ */
+declare function singletonTag(slug: string): string;
 interface MapboxConfigOptions {
     /** Cache lifetime in seconds on Next.js. Defaults to 3600. `0` disables caching, `false` caches until tag revalidation. Ignored outside Next.js. */
     revalidate?: number | false;
@@ -908,4 +935,57 @@ declare function revalidateAllTags(payload: Pick<WebhookEventPayload, "cache_tag
     expire?: number;
 }) => unknown): string[];
 
-export { type BookingStatus, CMS_CLIENT_VERSION, type CmsClientOptions, type CmsEvent, type CmsTicketTier, type ContentItem, type ContentQueryOptions, type ContentType, type ContentTypeSeoConfig, type CreateBookingParams, type CreateBookingResult, type CreateOrderParams, type CreateOrderResult, type DateGranularity, type DiscountType, type EmbedValue, type EventQueryOptions, type EventStatus, type EventWithTiers, type FieldDefinition, type FieldType, type FlipbookPagePublic, type FlipbookPublic, type FlipbookTocEntryPublic, type FormatPartialDateOptions, type GeocodeOptions, type GeocodeResult, type GoogleReview, IMAGE_PRESETS, type ImageConfig, type ImageTransformOptions, MAPBOX_CONFIG_TAG, type MapboxConfig, type MapboxConfigOptions, type MapsClientOptions, type MediaFolder, type MediaItem, type Member, type MembershipTier, type OrderAddress, type OrderLineItem, type OrderStatus, type ParsedPartialDate, type PaymentStatus, type Product, type ProductCategory, type ProductOption, type ProductQueryOptions, type ProductStatus, type ProductVariant, type Profile, type ReviewQueryOptions, TRACKING_CONFIG_TAG, type Tenant, type TenantMembership, type TrackingConfig, type TrackingConfigOptions, WEBHOOK_EVENTS, type WebhookEvent, type WebhookEventPayload, createCmsClient, createEventsClient, createMapsClient, createShopClient, formatPartialDate, getEmbedHtml, getSrcSet, getTransformUrl, parsePartialDate, revalidateAllTags, verifyWebhookSignature };
+/** Discriminator stamped on every visual-editing postMessage. */
+declare const CMS_VISUAL_SOURCE: "cms-visual";
+/** CMS origins the bridge will trust by default. */
+declare const DEFAULT_TRUSTED_ORIGINS: readonly string[];
+type VisualFieldType = "text" | "image";
+/** Compact wire type announced in `ready`; the schema adds length constraints. */
+interface VisualFieldMeta {
+    name: string;
+    type: VisualFieldType;
+}
+interface VisualFieldSchema {
+    name: string;
+    type: VisualFieldType;
+    max_length?: number;
+    recommended_length?: number;
+}
+interface ReadyMessage {
+    source: typeof CMS_VISUAL_SOURCE;
+    type: "ready";
+    fields: VisualFieldMeta[];
+}
+interface EditMessage {
+    source: typeof CMS_VISUAL_SOURCE;
+    type: "edit";
+    name: string;
+    value: string;
+    length: number;
+}
+interface PickImageMessage {
+    source: typeof CMS_VISUAL_SOURCE;
+    type: "pick-image";
+    name: string;
+}
+interface InitMessage {
+    source: typeof CMS_VISUAL_SOURCE;
+    type: "init";
+    values: Record<string, string>;
+    schema: Record<string, VisualFieldSchema>;
+}
+interface SetMessage {
+    source: typeof CMS_VISUAL_SOURCE;
+    type: "set";
+    name: string;
+    value: string;
+}
+type BridgeOutbound = ReadyMessage | EditMessage | PickImageMessage;
+type BridgeInbound = InitMessage | SetMessage;
+type VisualMessage = BridgeOutbound | BridgeInbound;
+/** Exact-match origin allowlist, plus any localhost port for local dev. */
+declare function isTrustedOrigin(origin: string, allowlist: readonly string[]): boolean;
+/** Narrow an unknown postMessage payload to a visual message, or null. */
+declare function parseVisualMessage(data: unknown): VisualMessage | null;
+
+export { type BookingStatus, type BridgeInbound, type BridgeOutbound, CMS_CLIENT_VERSION, CMS_VISUAL_SOURCE, type CmsClientOptions, type CmsEvent, type CmsTicketTier, type ContentItem, type ContentQueryOptions, type ContentType, type ContentTypeSeoConfig, type CreateBookingParams, type CreateBookingResult, type CreateOrderParams, type CreateOrderResult, DEFAULT_TRUSTED_ORIGINS, type DateGranularity, type DiscountType, type EditMessage, type EmbedValue, type EventQueryOptions, type EventStatus, type EventWithTiers, type FieldDefinition, type FieldType, type FlipbookPagePublic, type FlipbookPublic, type FlipbookTocEntryPublic, type FormatPartialDateOptions, type GeocodeOptions, type GeocodeResult, type GoogleReview, IMAGE_PRESETS, type ImageConfig, type ImageTransformOptions, type InitMessage, MAPBOX_CONFIG_TAG, type MapboxConfig, type MapboxConfigOptions, type MapsClientOptions, type MediaFolder, type MediaItem, type Member, type MembershipTier, type OrderAddress, type OrderLineItem, type OrderStatus, type ParsedPartialDate, type PaymentStatus, type PickImageMessage, type Product, type ProductCategory, type ProductOption, type ProductQueryOptions, type ProductStatus, type ProductVariant, type Profile, type ReadyMessage, type ReviewQueryOptions, type SetMessage, TRACKING_CONFIG_TAG, type Tenant, type TenantMembership, type TrackingConfig, type TrackingConfigOptions, type VisualFieldMeta, type VisualFieldSchema, type VisualFieldType, type VisualMessage, WEBHOOK_EVENTS, type WebhookEvent, type WebhookEventPayload, createCmsClient, createEventsClient, createMapsClient, createShopClient, formatPartialDate, getEmbedHtml, getSrcSet, getTransformUrl, isTrustedOrigin, parsePartialDate, parseVisualMessage, revalidateAllTags, singletonTag, verifyWebhookSignature };

package/dist/index.js

@@ -21,6 +21,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var src_exports = {};
 __export(src_exports, {
   CMS_CLIENT_VERSION: () => CMS_CLIENT_VERSION,
+  CMS_VISUAL_SOURCE: () => CMS_VISUAL_SOURCE,
+  DEFAULT_TRUSTED_ORIGINS: () => DEFAULT_TRUSTED_ORIGINS,
   IMAGE_PRESETS: () => IMAGE_PRESETS,
   MAPBOX_CONFIG_TAG: () => MAPBOX_CONFIG_TAG,
   TRACKING_CONFIG_TAG: () => TRACKING_CONFIG_TAG,
@@ -33,14 +35,17 @@ __export(src_exports, {
   getEmbedHtml: () => getEmbedHtml,
   getSrcSet: () => getSrcSet,
   getTransformUrl: () => getTransformUrl,
+  isTrustedOrigin: () => isTrustedOrigin,
   parsePartialDate: () => parsePartialDate,
+  parseVisualMessage: () => parseVisualMessage,
   revalidateAllTags: () => revalidateAllTags,
+  singletonTag: () => singletonTag,
   verifyWebhookSignature: () => verifyWebhookSignature
 });
 module.exports = __toCommonJS(src_exports);
 
 // src/version.ts
-var CMS_CLIENT_VERSION = "1.23.0";
+var CMS_CLIENT_VERSION = "1.25.0";
 
 // src/queries.ts
 var import_supabase_js = require("@supabase/supabase-js");
@@ -216,6 +221,27 @@ function createCmsClient(supabase, options) {
       }
       return data;
     },
+    /**
+     * Get the single published item for a singleton content type ("page").
+     *
+     * A singleton content type owns exactly one item. Use this for editable
+     * page copy (hero text, section headings, etc.) stored in the CMS.
+     * Returns null when the singleton has no published item yet — callers
+     * should fall back to their hardcoded defaults in that case.
+     *
+     * Wrap this in `unstable_cache` with a `cms:singleton:<slug>` tag on the
+     * consuming site to cache it and revalidate via the CMS webhook.
+     */
+    async getSingleton(contentTypeSlug) {
+      const contentTypeId = await getContentTypeId(contentTypeSlug);
+      const { data, error } = await client.from("content_items").select("*").eq("content_type_id", contentTypeId).eq("status", "published").order("updated_at", { ascending: false }).limit(1).maybeSingle();
+      if (error) {
+        throw new Error(
+          `Failed to fetch singleton ${contentTypeSlug}: ${error.message}`
+        );
+      }
+      return data ?? null;
+    },
     /**
      * Get a content type definition (including its field schema).
      */
@@ -418,6 +444,9 @@ function createCmsClient(supabase, options) {
 }
 var TRACKING_CONFIG_TAG = "cms:tracking-config";
 var MAPBOX_CONFIG_TAG = "cms:mapbox-config";
+function singletonTag(slug) {
+  return `cms:singleton:${slug}`;
+}
 function nullify(v) {
   if (!v) return null;
   const trimmed = v.trim();
@@ -772,9 +801,29 @@ function timingSafeEqualHex(a, b) {
   }
   return mismatch === 0;
 }
+
+// src/visual-editing/protocol.ts
+var CMS_VISUAL_SOURCE = "cms-visual";
+var DEFAULT_TRUSTED_ORIGINS = [
+  "https://cms.distinctstudio.co.nz",
+  "https://distinctcms.com"
+];
+function isTrustedOrigin(origin, allowlist) {
+  if (allowlist.includes(origin)) return true;
+  return /^https?:\/\/localhost(:\d+)?$/.test(origin);
+}
+var VALID_VISUAL_TYPES = /* @__PURE__ */ new Set(["ready", "edit", "pick-image", "init", "set"]);
+function parseVisualMessage(data) {
+  if (typeof data === "object" && data !== null && data.source === CMS_VISUAL_SOURCE && typeof data.type === "string" && VALID_VISUAL_TYPES.has(data.type)) {
+    return data;
+  }
+  return null;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CMS_CLIENT_VERSION,
+  CMS_VISUAL_SOURCE,
+  DEFAULT_TRUSTED_ORIGINS,
   IMAGE_PRESETS,
   MAPBOX_CONFIG_TAG,
   TRACKING_CONFIG_TAG,
@@ -787,8 +836,11 @@ function timingSafeEqualHex(a, b) {
   getEmbedHtml,
   getSrcSet,
   getTransformUrl,
+  isTrustedOrigin,
   parsePartialDate,
+  parseVisualMessage,
   revalidateAllTags,
+  singletonTag,
   verifyWebhookSignature
 });
 //# sourceMappingURL=index.js.map