@cmssy/core 9.4.0 → 9.6.0

package/dist/index.cjs

@@ -747,6 +747,139 @@ function localizeHtmlLinks(html, locale) {
   );
 }
 
+// src/data/relation-resolver.ts
+var RECORDS_BY_IDS_QUERY = `query PublicRecordsByIds($workspaceId: String!, $ids: [String!]!, $locale: String) {
+  public {
+    model {
+      recordsByIds(workspaceId: $workspaceId, ids: $ids, locale: $locale) {
+        id modelId data status createdAt updatedAt
+      }
+    }
+  }
+}`;
+var BY_IDS_CHUNK = 50;
+var COLLECTION_DEFAULT_LIMIT = 50;
+function relationModel(field) {
+  return field.relationTo?.startsWith("model:") ? field.relationTo.slice("model:".length) : void 0;
+}
+function storedIds(value) {
+  if (typeof value === "string" && value) return [value];
+  if (Array.isArray(value)) {
+    return value.filter((id) => typeof id === "string" && !!id);
+  }
+  return [];
+}
+function collectRefs(entries, schemas) {
+  const refs = [];
+  for (const entry of entries) {
+    const schema = schemas[entry.type];
+    if (!schema) continue;
+    for (const [key, field] of Object.entries(schema)) {
+      if (field.type !== "relation") continue;
+      const model = relationModel(field);
+      if (!model) continue;
+      refs.push({ content: entry.content, key, field, model });
+    }
+  }
+  return refs;
+}
+function collectionKey(ref) {
+  return [ref.model, ref.field.sort ?? "", ref.field.limit ?? ""].join("\0");
+}
+async function resolveRelationContent(config, entries, schemas, locale, requestOptions = {}) {
+  const refs = collectRefs(entries, schemas);
+  if (refs.length === 0) return;
+  const client = createCmssyClient(config);
+  const pickedIds = /* @__PURE__ */ new Set();
+  const collections = /* @__PURE__ */ new Map();
+  for (const ref of refs) {
+    if (ref.field.relationMode === "all") {
+      collections.set(collectionKey(ref), {
+        model: ref.model,
+        sort: ref.field.sort,
+        limit: ref.field.limit
+      });
+    } else {
+      for (const id of storedIds(ref.content[ref.key])) pickedIds.add(id);
+    }
+  }
+  let recordsById;
+  let collectionItems;
+  try {
+    [recordsById, collectionItems] = await Promise.all([
+      fetchPickedRecords(client, [...pickedIds], locale, requestOptions),
+      fetchCollections(client, collections, locale, requestOptions)
+    ]);
+  } catch (err) {
+    if (typeof console !== "undefined") {
+      console.error("[cmssy] relation resolution failed", err);
+    }
+    for (const ref of refs) {
+      if (ref.field.relationMode === "all" || Array.isArray(ref.content[ref.key])) {
+        ref.content[ref.key] = [];
+      } else {
+        delete ref.content[ref.key];
+      }
+    }
+    return;
+  }
+  for (const ref of refs) {
+    if (ref.field.relationMode === "all") {
+      ref.content[ref.key] = collectionItems.get(collectionKey(ref)) ?? [];
+      continue;
+    }
+    const value = ref.content[ref.key];
+    if (Array.isArray(value)) {
+      ref.content[ref.key] = storedIds(value).map((id) => recordsById.get(id)).filter((record) => !!record);
+    } else if (typeof value === "string" && value) {
+      const record = recordsById.get(value);
+      if (record) ref.content[ref.key] = record;
+      else delete ref.content[ref.key];
+    } else {
+      delete ref.content[ref.key];
+    }
+  }
+}
+async function fetchPickedRecords(client, ids, locale, requestOptions = {}) {
+  const byId = /* @__PURE__ */ new Map();
+  const chunks = [];
+  for (let i = 0; i < ids.length; i += BY_IDS_CHUNK) {
+    chunks.push(ids.slice(i, i + BY_IDS_CHUNK));
+  }
+  await Promise.all(
+    chunks.map(async (chunk) => {
+      const result = await client.queryScoped(
+        RECORDS_BY_IDS_QUERY,
+        { ids: chunk, locale: locale ?? null },
+        requestOptions
+      );
+      for (const record of result.public.model.recordsByIds) {
+        byId.set(record.id, record);
+      }
+    })
+  );
+  return byId;
+}
+async function fetchCollections(client, collections, locale, requestOptions = {}) {
+  const byKey = /* @__PURE__ */ new Map();
+  await Promise.all(
+    [...collections.entries()].map(async ([key, { model, sort, limit }]) => {
+      const result = await client.queryScoped(
+        MODEL_RECORDS_QUERY,
+        {
+          modelSlug: model,
+          sort: sort ?? null,
+          limit: limit ?? COLLECTION_DEFAULT_LIMIT,
+          locale: locale ?? null
+        },
+        requestOptions
+      );
+      byKey.set(key, result.public.model.records.items);
+    })
+  );
+  return byKey;
+}
+
 // src/locale.ts
 var CMSSY_LOCALE_HEADER = "x-cmssy-locale";
 async function localeForPathname(config, pathname) {
@@ -810,7 +943,16 @@ var fields = {
   radio: choice("radio"),
   multiselect: (opts) => build("multiselect", opts),
   media: (opts = {}) => build("media", opts),
-  repeater: (opts) => build("repeater", opts)
+  repeater: (opts) => build("repeater", opts),
+  relation: (opts) => {
+    const { model, mode, ...rest } = opts;
+    return build("relation", {
+      ...rest,
+      relationTo: `model:${model}`,
+      relationType: mode === "all" || opts.multiple ? "hasMany" : "hasOne",
+      relationMode: mode ?? "picked"
+    });
+  }
 };
 
 // src/bridge/protocol.ts
@@ -1747,6 +1889,7 @@ exports.MODEL_DEFINITIONS_QUERY = MODEL_DEFINITIONS_QUERY;
 exports.MODEL_RECORDS_QUERY = MODEL_RECORDS_QUERY;
 exports.PRODUCTS_QUERY = PRODUCTS_QUERY;
 exports.PROTOCOL_VERSION = PROTOCOL_VERSION;
+exports.RECORDS_BY_IDS_QUERY = RECORDS_BY_IDS_QUERY;
 exports.SESSION_MAX_AGE_SECONDS = SESSION_MAX_AGE_SECONDS;
 exports.SITE_CONFIG_QUERY = SITE_CONFIG_QUERY;
 exports.SUBMIT_FORM_MUTATION = SUBMIT_FORM_MUTATION;
@@ -1820,6 +1963,7 @@ exports.resolveEditorOrigin = resolveEditorOrigin;
 exports.resolveForms = resolveForms;
 exports.resolveInitialTarget = resolveInitialTarget;
 exports.resolvePublicUrl = resolvePublicUrl;
+exports.resolveRelationContent = resolveRelationContent;
 exports.resolveSiteLocales = resolveSiteLocales;
 exports.resolveWorkspaceId = resolveWorkspaceId;
 exports.sealSession = sealSession;

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import * as _cmssy_types from '@cmssy/types';
-import { CmssyAuthConfig, CmssyClientConfig, CmssySiteConfig, RawBlock, CmssyFormDefinition, CmssySiteLocales, BuildBlockContextExtra, CmssyBlockContext, CmssyLocaleContext, FieldOptions, TypedField, BlockPropsSchema, InferBlockContent, BlockRect, BlockSchema, BlockMeta, CmssySessionPayload, SessionCookieOptions, CmssySessionUser, CmssyAddress, CmssyCart, CmssyOrder, CmssyProduct, MyOrdersResult, FetchProductOptions, FetchProductsOptions, CmssyProductPage, FetchOrderByTokenOptions, VerifyCmssyWebhookOptions, CmssyWebhookEvent } from '@cmssy/types';
+import { CmssyAuthConfig, CmssyClientConfig, CmssySiteConfig, RawBlock, CmssyFormDefinition, CmssySiteLocales, BuildBlockContextExtra, CmssyBlockContext, CmssyLocaleContext, FieldDefinition, FieldOptions, TypedField, BlockPropsSchema, InferBlockContent, RelationMode, CmssyModelRecord, BlockRect, BlockSchema, BlockMeta, CmssySessionPayload, SessionCookieOptions, CmssySessionUser, CmssyAddress, CmssyCart, CmssyOrder, CmssyProduct, MyOrdersResult, FetchProductOptions, FetchProductsOptions, CmssyProductPage, FetchOrderByTokenOptions, VerifyCmssyWebhookOptions, CmssyWebhookEvent } from '@cmssy/types';
 export { BlockMeta, BlockPropsSchema, BlockRect, BlockSchema, BuildBlockContextExtra, CmssyAddress, CmssyAuthConfig, CmssyBlockAuthContext, CmssyBlockContext, CmssyBlockMember, CmssyBlockWorkspace, CmssyBranding, CmssyCart, CmssyCartDiscount, CmssyCartItem, CmssyCartItemSnapshot, CmssyClientConfig, CmssyFormDefinition, CmssyFormField, CmssyFormSettings, CmssyFormSubmitResponse, CmssyLayoutGroup, CmssyLayoutSettings, CmssyLocaleContext, CmssyLocalizedValue, CmssyModelDefinition, CmssyModelRecord, CmssyOrder, CmssyOrderDiscount, CmssyOrderItem, CmssyOrderTaxSummaryLine, CmssyPageData, CmssyPageMeta, CmssyPageSummary, CmssyPriceTier, CmssyProduct, CmssyProductPage, CmssyProductVariant, CmssyRecordList, CmssySessionPayload, CmssySessionUser, CmssyShippingMethod, CmssySiteConfig, CmssySiteLocales, CmssyStockState, CmssyTaxSummaryLine, CmssyWebhookEvent, CmssyWebhookOrder, FetchOrderByTokenOptions, FetchProductOptions, FetchProductsOptions, FieldCondition, FieldConditionGroup, FieldConditionLogic, FieldControl, FieldDefinition, FieldOptions, FieldType, InferBlockContent, MyOrdersResult, RawBlock, RawLayoutBlock, SessionCookieOptions, SubmitFormInput, TypedField, VerifyCmssyWebhookOptions, evaluateFieldConditionGroup } from '@cmssy/types';
 import { F as FetchLike, R as RetryPolicy } from './content-client-D0EdiqbQ.cjs';
 export { C as CmssyRequestError, D as DEFAULT_CMSSY_API_URL, a as FetchLikeResponse, b as FetchPageOptions, f as fetchLayouts, c as fetchPage, d as fetchPageById, e as fetchPageMeta, g as fetchPages, n as normalizeSlug, r as resolveApiUrl, h as resolvePublicUrl } from './content-client-D0EdiqbQ.cjs';
@@ -158,6 +158,21 @@ declare function buildLocaleSwitchHref(target: string, pathname: string, locale:
  */
 declare function localizeHtmlLinks(html: string, locale: CmssyLocaleContext): string;
 
+declare const RECORDS_BY_IDS_QUERY = "query PublicRecordsByIds($workspaceId: String!, $ids: [String!]!, $locale: String) {\n  public {\n    model {\n      recordsByIds(workspaceId: $workspaceId, ids: $ids, locale: $locale) {\n        id modelId data status createdAt updatedAt\n      }\n    }\n  }\n}";
+interface RelationContentEntry {
+    type: string;
+    content: Record<string, unknown>;
+}
+type BlockSchemaMap = Record<string, Record<string, FieldDefinition>>;
+/**
+ * Resolves every `fields.relation` value on the given block contents in place:
+ * stored record ids become full records (one batched read for the whole page),
+ * and a `mode: "all"` field becomes the model's record list. A dangling id and
+ * a failed fetch both degrade to "no value" - a relation must never break a
+ * render.
+ */
+declare function resolveRelationContent(config: CmssyClientConfig, entries: RelationContentEntry[], schemas: BlockSchemaMap, locale?: string, requestOptions?: QueryScopedOptions): Promise<void>;
+
 declare const CMSSY_LOCALE_HEADER = "x-cmssy-locale";
 declare function localeForPathname(config: CmssyClientConfig, pathname: string): Promise<string>;
 declare function splitCmssyLocale(config: CmssyClientConfig, path: string[] | undefined): Promise<{
@@ -182,6 +197,30 @@ type MediaValue<O> = O extends {
 type RepeaterValue<O> = O extends {
     itemSchema: infer Schema extends BlockPropsSchema;
 } ? InferBlockContent<Schema>[] : Record<string, unknown>[];
+/**
+ * The value a relation field holds AFTER server-side resolution: the SDK
+ * replaces the stored record id(s) with the records themselves before the
+ * component renders. `mode: "all"` and `multiple: true` yield a list; the
+ * default is a single record - `undefined` when the reference dangles, which
+ * no `required` flag can rule out.
+ */
+type RelationValue<O> = O extends {
+    mode: "all";
+} | {
+    multiple: true;
+} ? CmssyModelRecord[] : CmssyModelRecord | undefined;
+interface RelationFieldOptions extends Omit<FieldOptions, "options" | "itemSchema"> {
+    /** Slug of the model the field points at. */
+    model: string;
+    /**
+     * "all" binds the field to every record of the model (no editor picking;
+     * `sort`/`limit` shape the list). Omit it for editor-picked record id(s).
+     */
+    mode?: RelationMode;
+    multiple?: boolean;
+    sort?: string;
+    limit?: number;
+}
 declare const fields: {
     text: <const O extends FieldOptions>(opts?: O) => TypedField<string, Declared<O>>;
     textarea: <const O extends FieldOptions>(opts?: O) => TypedField<string, Declared<O>>;
@@ -204,6 +243,7 @@ declare const fields: {
     multiselect: <const O extends FieldOptions>(opts: O) => TypedField<OptionValue<O>[], Declared<O>>;
     media: <const O extends FieldOptions>(opts?: O) => TypedField<MediaValue<O>, Declared<O>>;
     repeater: <const O extends FieldOptions>(opts: O) => TypedField<RepeaterValue<O>, Declared<O>>;
+    relation: <const O extends RelationFieldOptions>(opts: O) => TypedField<RelationValue<O>, Declared<O>>;
 };
 
 declare const PROTOCOL_VERSION = 2;
@@ -447,4 +487,4 @@ declare class CmssyWebhookError extends Error {
  */
 declare function verifyCmssyWebhook(options: VerifyCmssyWebhookOptions): Promise<CmssyWebhookEvent>;
 
-export { type AppToEditorMessage, type AuthMutationResult, type AuthTokenResult, type BoundsMessage, CMSSY_EDIT_HEADER, CMSSY_EDIT_QUERY_PARAM, CMSSY_LOCALE_HEADER, CMSSY_SECRET_QUERY_PARAM, CMSSY_SESSION_COOKIE, type CartRequestContext, type CheckoutInput, type ClickMessage, type CmssyClient, type CmssyConfig, type CmssyCspOptions, type CmssyEnvConfig, CmssyWebhookError, DEFAULT_CMSSY_EDITOR_ORIGINS, type EditorToAppMessage, FORM_QUERY, FetchLike, type GraphqlRequestOptions, MIN_SESSION_SECRET_LENGTH, MODEL_DEFINITIONS_QUERY, MODEL_RECORDS_QUERY, PRODUCTS_QUERY, PROTOCOL_VERSION, type ParentReadyMessage, type PatchMessage, type PostTarget, type QueryScopedOptions, type ReadyMessage, RetryPolicy, SESSION_MAX_AGE_SECONDS, SITE_CONFIG_QUERY, SUBMIT_FORM_MUTATION, type SelectMessage, applyCmssyCsp, asBucket, assertAuthConfig, backendAddToCart, backendApplyDiscount, backendCheckout, backendClearCart, backendForgotPassword, backendGetCart, backendMergeCart, backendMyOrder, backendMyOrders, backendOrderByToken, backendProduct, backendRefresh, backendRegister, backendRemoveDiscount, backendRemoveItem, backendResetPassword, backendSetShippingMethod, backendSignIn, backendSignOut, backendSignOutEverywhere, backendUpdateItem, backendVerifyEmail, buildBlockContext, buildLocaleSwitchHref, cachedWorkspaceId, clearWorkspaceIdCache, cmssyCspHeaders, cmssySecretsMatch, collectFormIds, createCmssyClient, decodeAccessClaims, defineCmssyConfig, fetchOrderByToken, fetchProduct, fetchProducts, fetchSiteConfig, fields, formatPrice, fractionDigits, fromMinorUnits, getBlockContentForLanguage, graphqlRequest, isAccessExpired, isDevelopment, isProtocolCompatible, isVerifiedEditUrl, localeForPath, localeForPathname, localesFromSiteConfig, localizeHref, localizeHtmlLinks, localizedPath, normalizeOrigin, openSession, parseEditorMessage, postToEditor, resolveEditorOrigin, resolveForms, resolveInitialTarget, resolveSiteLocales, resolveWorkspaceId, sealSession, sessionCookieOptions, splitCmssyLocale, splitLocaleFromPath, toCspOrigin, toMinorUnits, toSessionPayload, verifyCmssyWebhook };
+export { type AppToEditorMessage, type AuthMutationResult, type AuthTokenResult, type BlockSchemaMap, type BoundsMessage, CMSSY_EDIT_HEADER, CMSSY_EDIT_QUERY_PARAM, CMSSY_LOCALE_HEADER, CMSSY_SECRET_QUERY_PARAM, CMSSY_SESSION_COOKIE, type CartRequestContext, type CheckoutInput, type ClickMessage, type CmssyClient, type CmssyConfig, type CmssyCspOptions, type CmssyEnvConfig, CmssyWebhookError, DEFAULT_CMSSY_EDITOR_ORIGINS, type EditorToAppMessage, FORM_QUERY, FetchLike, type GraphqlRequestOptions, MIN_SESSION_SECRET_LENGTH, MODEL_DEFINITIONS_QUERY, MODEL_RECORDS_QUERY, PRODUCTS_QUERY, PROTOCOL_VERSION, type ParentReadyMessage, type PatchMessage, type PostTarget, type QueryScopedOptions, RECORDS_BY_IDS_QUERY, type ReadyMessage, type RelationContentEntry, RetryPolicy, SESSION_MAX_AGE_SECONDS, SITE_CONFIG_QUERY, SUBMIT_FORM_MUTATION, type SelectMessage, applyCmssyCsp, asBucket, assertAuthConfig, backendAddToCart, backendApplyDiscount, backendCheckout, backendClearCart, backendForgotPassword, backendGetCart, backendMergeCart, backendMyOrder, backendMyOrders, backendOrderByToken, backendProduct, backendRefresh, backendRegister, backendRemoveDiscount, backendRemoveItem, backendResetPassword, backendSetShippingMethod, backendSignIn, backendSignOut, backendSignOutEverywhere, backendUpdateItem, backendVerifyEmail, buildBlockContext, buildLocaleSwitchHref, cachedWorkspaceId, clearWorkspaceIdCache, cmssyCspHeaders, cmssySecretsMatch, collectFormIds, createCmssyClient, decodeAccessClaims, defineCmssyConfig, fetchOrderByToken, fetchProduct, fetchProducts, fetchSiteConfig, fields, formatPrice, fractionDigits, fromMinorUnits, getBlockContentForLanguage, graphqlRequest, isAccessExpired, isDevelopment, isProtocolCompatible, isVerifiedEditUrl, localeForPath, localeForPathname, localesFromSiteConfig, localizeHref, localizeHtmlLinks, localizedPath, normalizeOrigin, openSession, parseEditorMessage, postToEditor, resolveEditorOrigin, resolveForms, resolveInitialTarget, resolveRelationContent, resolveSiteLocales, resolveWorkspaceId, sealSession, sessionCookieOptions, splitCmssyLocale, splitLocaleFromPath, toCspOrigin, toMinorUnits, toSessionPayload, verifyCmssyWebhook };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _cmssy_types from '@cmssy/types';
-import { CmssyAuthConfig, CmssyClientConfig, CmssySiteConfig, RawBlock, CmssyFormDefinition, CmssySiteLocales, BuildBlockContextExtra, CmssyBlockContext, CmssyLocaleContext, FieldOptions, TypedField, BlockPropsSchema, InferBlockContent, BlockRect, BlockSchema, BlockMeta, CmssySessionPayload, SessionCookieOptions, CmssySessionUser, CmssyAddress, CmssyCart, CmssyOrder, CmssyProduct, MyOrdersResult, FetchProductOptions, FetchProductsOptions, CmssyProductPage, FetchOrderByTokenOptions, VerifyCmssyWebhookOptions, CmssyWebhookEvent } from '@cmssy/types';
+import { CmssyAuthConfig, CmssyClientConfig, CmssySiteConfig, RawBlock, CmssyFormDefinition, CmssySiteLocales, BuildBlockContextExtra, CmssyBlockContext, CmssyLocaleContext, FieldDefinition, FieldOptions, TypedField, BlockPropsSchema, InferBlockContent, RelationMode, CmssyModelRecord, BlockRect, BlockSchema, BlockMeta, CmssySessionPayload, SessionCookieOptions, CmssySessionUser, CmssyAddress, CmssyCart, CmssyOrder, CmssyProduct, MyOrdersResult, FetchProductOptions, FetchProductsOptions, CmssyProductPage, FetchOrderByTokenOptions, VerifyCmssyWebhookOptions, CmssyWebhookEvent } from '@cmssy/types';
 export { BlockMeta, BlockPropsSchema, BlockRect, BlockSchema, BuildBlockContextExtra, CmssyAddress, CmssyAuthConfig, CmssyBlockAuthContext, CmssyBlockContext, CmssyBlockMember, CmssyBlockWorkspace, CmssyBranding, CmssyCart, CmssyCartDiscount, CmssyCartItem, CmssyCartItemSnapshot, CmssyClientConfig, CmssyFormDefinition, CmssyFormField, CmssyFormSettings, CmssyFormSubmitResponse, CmssyLayoutGroup, CmssyLayoutSettings, CmssyLocaleContext, CmssyLocalizedValue, CmssyModelDefinition, CmssyModelRecord, CmssyOrder, CmssyOrderDiscount, CmssyOrderItem, CmssyOrderTaxSummaryLine, CmssyPageData, CmssyPageMeta, CmssyPageSummary, CmssyPriceTier, CmssyProduct, CmssyProductPage, CmssyProductVariant, CmssyRecordList, CmssySessionPayload, CmssySessionUser, CmssyShippingMethod, CmssySiteConfig, CmssySiteLocales, CmssyStockState, CmssyTaxSummaryLine, CmssyWebhookEvent, CmssyWebhookOrder, FetchOrderByTokenOptions, FetchProductOptions, FetchProductsOptions, FieldCondition, FieldConditionGroup, FieldConditionLogic, FieldControl, FieldDefinition, FieldOptions, FieldType, InferBlockContent, MyOrdersResult, RawBlock, RawLayoutBlock, SessionCookieOptions, SubmitFormInput, TypedField, VerifyCmssyWebhookOptions, evaluateFieldConditionGroup } from '@cmssy/types';
 import { F as FetchLike, R as RetryPolicy } from './content-client-D0EdiqbQ.js';
 export { C as CmssyRequestError, D as DEFAULT_CMSSY_API_URL, a as FetchLikeResponse, b as FetchPageOptions, f as fetchLayouts, c as fetchPage, d as fetchPageById, e as fetchPageMeta, g as fetchPages, n as normalizeSlug, r as resolveApiUrl, h as resolvePublicUrl } from './content-client-D0EdiqbQ.js';
@@ -158,6 +158,21 @@ declare function buildLocaleSwitchHref(target: string, pathname: string, locale:
  */
 declare function localizeHtmlLinks(html: string, locale: CmssyLocaleContext): string;
 
+declare const RECORDS_BY_IDS_QUERY = "query PublicRecordsByIds($workspaceId: String!, $ids: [String!]!, $locale: String) {\n  public {\n    model {\n      recordsByIds(workspaceId: $workspaceId, ids: $ids, locale: $locale) {\n        id modelId data status createdAt updatedAt\n      }\n    }\n  }\n}";
+interface RelationContentEntry {
+    type: string;
+    content: Record<string, unknown>;
+}
+type BlockSchemaMap = Record<string, Record<string, FieldDefinition>>;
+/**
+ * Resolves every `fields.relation` value on the given block contents in place:
+ * stored record ids become full records (one batched read for the whole page),
+ * and a `mode: "all"` field becomes the model's record list. A dangling id and
+ * a failed fetch both degrade to "no value" - a relation must never break a
+ * render.
+ */
+declare function resolveRelationContent(config: CmssyClientConfig, entries: RelationContentEntry[], schemas: BlockSchemaMap, locale?: string, requestOptions?: QueryScopedOptions): Promise<void>;
+
 declare const CMSSY_LOCALE_HEADER = "x-cmssy-locale";
 declare function localeForPathname(config: CmssyClientConfig, pathname: string): Promise<string>;
 declare function splitCmssyLocale(config: CmssyClientConfig, path: string[] | undefined): Promise<{
@@ -182,6 +197,30 @@ type MediaValue<O> = O extends {
 type RepeaterValue<O> = O extends {
     itemSchema: infer Schema extends BlockPropsSchema;
 } ? InferBlockContent<Schema>[] : Record<string, unknown>[];
+/**
+ * The value a relation field holds AFTER server-side resolution: the SDK
+ * replaces the stored record id(s) with the records themselves before the
+ * component renders. `mode: "all"` and `multiple: true` yield a list; the
+ * default is a single record - `undefined` when the reference dangles, which
+ * no `required` flag can rule out.
+ */
+type RelationValue<O> = O extends {
+    mode: "all";
+} | {
+    multiple: true;
+} ? CmssyModelRecord[] : CmssyModelRecord | undefined;
+interface RelationFieldOptions extends Omit<FieldOptions, "options" | "itemSchema"> {
+    /** Slug of the model the field points at. */
+    model: string;
+    /**
+     * "all" binds the field to every record of the model (no editor picking;
+     * `sort`/`limit` shape the list). Omit it for editor-picked record id(s).
+     */
+    mode?: RelationMode;
+    multiple?: boolean;
+    sort?: string;
+    limit?: number;
+}
 declare const fields: {
     text: <const O extends FieldOptions>(opts?: O) => TypedField<string, Declared<O>>;
     textarea: <const O extends FieldOptions>(opts?: O) => TypedField<string, Declared<O>>;
@@ -204,6 +243,7 @@ declare const fields: {
     multiselect: <const O extends FieldOptions>(opts: O) => TypedField<OptionValue<O>[], Declared<O>>;
     media: <const O extends FieldOptions>(opts?: O) => TypedField<MediaValue<O>, Declared<O>>;
     repeater: <const O extends FieldOptions>(opts: O) => TypedField<RepeaterValue<O>, Declared<O>>;
+    relation: <const O extends RelationFieldOptions>(opts: O) => TypedField<RelationValue<O>, Declared<O>>;
 };
 
 declare const PROTOCOL_VERSION = 2;
@@ -447,4 +487,4 @@ declare class CmssyWebhookError extends Error {
  */
 declare function verifyCmssyWebhook(options: VerifyCmssyWebhookOptions): Promise<CmssyWebhookEvent>;
 
-export { type AppToEditorMessage, type AuthMutationResult, type AuthTokenResult, type BoundsMessage, CMSSY_EDIT_HEADER, CMSSY_EDIT_QUERY_PARAM, CMSSY_LOCALE_HEADER, CMSSY_SECRET_QUERY_PARAM, CMSSY_SESSION_COOKIE, type CartRequestContext, type CheckoutInput, type ClickMessage, type CmssyClient, type CmssyConfig, type CmssyCspOptions, type CmssyEnvConfig, CmssyWebhookError, DEFAULT_CMSSY_EDITOR_ORIGINS, type EditorToAppMessage, FORM_QUERY, FetchLike, type GraphqlRequestOptions, MIN_SESSION_SECRET_LENGTH, MODEL_DEFINITIONS_QUERY, MODEL_RECORDS_QUERY, PRODUCTS_QUERY, PROTOCOL_VERSION, type ParentReadyMessage, type PatchMessage, type PostTarget, type QueryScopedOptions, type ReadyMessage, RetryPolicy, SESSION_MAX_AGE_SECONDS, SITE_CONFIG_QUERY, SUBMIT_FORM_MUTATION, type SelectMessage, applyCmssyCsp, asBucket, assertAuthConfig, backendAddToCart, backendApplyDiscount, backendCheckout, backendClearCart, backendForgotPassword, backendGetCart, backendMergeCart, backendMyOrder, backendMyOrders, backendOrderByToken, backendProduct, backendRefresh, backendRegister, backendRemoveDiscount, backendRemoveItem, backendResetPassword, backendSetShippingMethod, backendSignIn, backendSignOut, backendSignOutEverywhere, backendUpdateItem, backendVerifyEmail, buildBlockContext, buildLocaleSwitchHref, cachedWorkspaceId, clearWorkspaceIdCache, cmssyCspHeaders, cmssySecretsMatch, collectFormIds, createCmssyClient, decodeAccessClaims, defineCmssyConfig, fetchOrderByToken, fetchProduct, fetchProducts, fetchSiteConfig, fields, formatPrice, fractionDigits, fromMinorUnits, getBlockContentForLanguage, graphqlRequest, isAccessExpired, isDevelopment, isProtocolCompatible, isVerifiedEditUrl, localeForPath, localeForPathname, localesFromSiteConfig, localizeHref, localizeHtmlLinks, localizedPath, normalizeOrigin, openSession, parseEditorMessage, postToEditor, resolveEditorOrigin, resolveForms, resolveInitialTarget, resolveSiteLocales, resolveWorkspaceId, sealSession, sessionCookieOptions, splitCmssyLocale, splitLocaleFromPath, toCspOrigin, toMinorUnits, toSessionPayload, verifyCmssyWebhook };
+export { type AppToEditorMessage, type AuthMutationResult, type AuthTokenResult, type BlockSchemaMap, type BoundsMessage, CMSSY_EDIT_HEADER, CMSSY_EDIT_QUERY_PARAM, CMSSY_LOCALE_HEADER, CMSSY_SECRET_QUERY_PARAM, CMSSY_SESSION_COOKIE, type CartRequestContext, type CheckoutInput, type ClickMessage, type CmssyClient, type CmssyConfig, type CmssyCspOptions, type CmssyEnvConfig, CmssyWebhookError, DEFAULT_CMSSY_EDITOR_ORIGINS, type EditorToAppMessage, FORM_QUERY, FetchLike, type GraphqlRequestOptions, MIN_SESSION_SECRET_LENGTH, MODEL_DEFINITIONS_QUERY, MODEL_RECORDS_QUERY, PRODUCTS_QUERY, PROTOCOL_VERSION, type ParentReadyMessage, type PatchMessage, type PostTarget, type QueryScopedOptions, RECORDS_BY_IDS_QUERY, type ReadyMessage, type RelationContentEntry, RetryPolicy, SESSION_MAX_AGE_SECONDS, SITE_CONFIG_QUERY, SUBMIT_FORM_MUTATION, type SelectMessage, applyCmssyCsp, asBucket, assertAuthConfig, backendAddToCart, backendApplyDiscount, backendCheckout, backendClearCart, backendForgotPassword, backendGetCart, backendMergeCart, backendMyOrder, backendMyOrders, backendOrderByToken, backendProduct, backendRefresh, backendRegister, backendRemoveDiscount, backendRemoveItem, backendResetPassword, backendSetShippingMethod, backendSignIn, backendSignOut, backendSignOutEverywhere, backendUpdateItem, backendVerifyEmail, buildBlockContext, buildLocaleSwitchHref, cachedWorkspaceId, clearWorkspaceIdCache, cmssyCspHeaders, cmssySecretsMatch, collectFormIds, createCmssyClient, decodeAccessClaims, defineCmssyConfig, fetchOrderByToken, fetchProduct, fetchProducts, fetchSiteConfig, fields, formatPrice, fractionDigits, fromMinorUnits, getBlockContentForLanguage, graphqlRequest, isAccessExpired, isDevelopment, isProtocolCompatible, isVerifiedEditUrl, localeForPath, localeForPathname, localesFromSiteConfig, localizeHref, localizeHtmlLinks, localizedPath, normalizeOrigin, openSession, parseEditorMessage, postToEditor, resolveEditorOrigin, resolveForms, resolveInitialTarget, resolveRelationContent, resolveSiteLocales, resolveWorkspaceId, sealSession, sessionCookieOptions, splitCmssyLocale, splitLocaleFromPath, toCspOrigin, toMinorUnits, toSessionPayload, verifyCmssyWebhook };

package/dist/index.js

@@ -745,6 +745,139 @@ function localizeHtmlLinks(html, locale) {
   );
 }
 
+// src/data/relation-resolver.ts
+var RECORDS_BY_IDS_QUERY = `query PublicRecordsByIds($workspaceId: String!, $ids: [String!]!, $locale: String) {
+  public {
+    model {
+      recordsByIds(workspaceId: $workspaceId, ids: $ids, locale: $locale) {
+        id modelId data status createdAt updatedAt
+      }
+    }
+  }
+}`;
+var BY_IDS_CHUNK = 50;
+var COLLECTION_DEFAULT_LIMIT = 50;
+function relationModel(field) {
+  return field.relationTo?.startsWith("model:") ? field.relationTo.slice("model:".length) : void 0;
+}
+function storedIds(value) {
+  if (typeof value === "string" && value) return [value];
+  if (Array.isArray(value)) {
+    return value.filter((id) => typeof id === "string" && !!id);
+  }
+  return [];
+}
+function collectRefs(entries, schemas) {
+  const refs = [];
+  for (const entry of entries) {
+    const schema = schemas[entry.type];
+    if (!schema) continue;
+    for (const [key, field] of Object.entries(schema)) {
+      if (field.type !== "relation") continue;
+      const model = relationModel(field);
+      if (!model) continue;
+      refs.push({ content: entry.content, key, field, model });
+    }
+  }
+  return refs;
+}
+function collectionKey(ref) {
+  return [ref.model, ref.field.sort ?? "", ref.field.limit ?? ""].join("\0");
+}
+async function resolveRelationContent(config, entries, schemas, locale, requestOptions = {}) {
+  const refs = collectRefs(entries, schemas);
+  if (refs.length === 0) return;
+  const client = createCmssyClient(config);
+  const pickedIds = /* @__PURE__ */ new Set();
+  const collections = /* @__PURE__ */ new Map();
+  for (const ref of refs) {
+    if (ref.field.relationMode === "all") {
+      collections.set(collectionKey(ref), {
+        model: ref.model,
+        sort: ref.field.sort,
+        limit: ref.field.limit
+      });
+    } else {
+      for (const id of storedIds(ref.content[ref.key])) pickedIds.add(id);
+    }
+  }
+  let recordsById;
+  let collectionItems;
+  try {
+    [recordsById, collectionItems] = await Promise.all([
+      fetchPickedRecords(client, [...pickedIds], locale, requestOptions),
+      fetchCollections(client, collections, locale, requestOptions)
+    ]);
+  } catch (err) {
+    if (typeof console !== "undefined") {
+      console.error("[cmssy] relation resolution failed", err);
+    }
+    for (const ref of refs) {
+      if (ref.field.relationMode === "all" || Array.isArray(ref.content[ref.key])) {
+        ref.content[ref.key] = [];
+      } else {
+        delete ref.content[ref.key];
+      }
+    }
+    return;
+  }
+  for (const ref of refs) {
+    if (ref.field.relationMode === "all") {
+      ref.content[ref.key] = collectionItems.get(collectionKey(ref)) ?? [];
+      continue;
+    }
+    const value = ref.content[ref.key];
+    if (Array.isArray(value)) {
+      ref.content[ref.key] = storedIds(value).map((id) => recordsById.get(id)).filter((record) => !!record);
+    } else if (typeof value === "string" && value) {
+      const record = recordsById.get(value);
+      if (record) ref.content[ref.key] = record;
+      else delete ref.content[ref.key];
+    } else {
+      delete ref.content[ref.key];
+    }
+  }
+}
+async function fetchPickedRecords(client, ids, locale, requestOptions = {}) {
+  const byId = /* @__PURE__ */ new Map();
+  const chunks = [];
+  for (let i = 0; i < ids.length; i += BY_IDS_CHUNK) {
+    chunks.push(ids.slice(i, i + BY_IDS_CHUNK));
+  }
+  await Promise.all(
+    chunks.map(async (chunk) => {
+      const result = await client.queryScoped(
+        RECORDS_BY_IDS_QUERY,
+        { ids: chunk, locale: locale ?? null },
+        requestOptions
+      );
+      for (const record of result.public.model.recordsByIds) {
+        byId.set(record.id, record);
+      }
+    })
+  );
+  return byId;
+}
+async function fetchCollections(client, collections, locale, requestOptions = {}) {
+  const byKey = /* @__PURE__ */ new Map();
+  await Promise.all(
+    [...collections.entries()].map(async ([key, { model, sort, limit }]) => {
+      const result = await client.queryScoped(
+        MODEL_RECORDS_QUERY,
+        {
+          modelSlug: model,
+          sort: sort ?? null,
+          limit: limit ?? COLLECTION_DEFAULT_LIMIT,
+          locale: locale ?? null
+        },
+        requestOptions
+      );
+      byKey.set(key, result.public.model.records.items);
+    })
+  );
+  return byKey;
+}
+
 // src/locale.ts
 var CMSSY_LOCALE_HEADER = "x-cmssy-locale";
 async function localeForPathname(config, pathname) {
@@ -808,7 +941,16 @@ var fields = {
   radio: choice("radio"),
   multiselect: (opts) => build("multiselect", opts),
   media: (opts = {}) => build("media", opts),
-  repeater: (opts) => build("repeater", opts)
+  repeater: (opts) => build("repeater", opts),
+  relation: (opts) => {
+    const { model, mode, ...rest } = opts;
+    return build("relation", {
+      ...rest,
+      relationTo: `model:${model}`,
+      relationType: mode === "all" || opts.multiple ? "hasMany" : "hasOne",
+      relationMode: mode ?? "picked"
+    });
+  }
 };
 
 // src/bridge/protocol.ts
@@ -1726,4 +1868,4 @@ async function verifyCmssyWebhook(options) {
   return parsed;
 }
 
-export { CMSSY_EDIT_HEADER, CMSSY_EDIT_QUERY_PARAM, CMSSY_LOCALE_HEADER, CMSSY_SECRET_QUERY_PARAM, CMSSY_SESSION_COOKIE, CmssyRequestError, CmssyWebhookError, DEFAULT_CMSSY_API_URL, DEFAULT_CMSSY_EDITOR_ORIGINS, FORM_QUERY, MIN_SESSION_SECRET_LENGTH, MODEL_DEFINITIONS_QUERY, MODEL_RECORDS_QUERY, PRODUCTS_QUERY, PROTOCOL_VERSION, SESSION_MAX_AGE_SECONDS, SITE_CONFIG_QUERY, SUBMIT_FORM_MUTATION, applyCmssyCsp, asBucket, assertAuthConfig, backendAddToCart, backendApplyDiscount, backendCheckout, backendClearCart, backendForgotPassword, backendGetCart, backendMergeCart, backendMyOrder, backendMyOrders, backendOrderByToken, backendProduct, backendRefresh, backendRegister, backendRemoveDiscount, backendRemoveItem, backendResetPassword, backendSetShippingMethod, backendSignIn, backendSignOut, backendSignOutEverywhere, backendUpdateItem, backendVerifyEmail, buildBlockContext, buildLocaleSwitchHref, cachedWorkspaceId, clearWorkspaceIdCache, cmssyCspHeaders, cmssySecretsMatch, collectFormIds, createCmssyClient, decodeAccessClaims, defineCmssyConfig, fetchLayouts, fetchOrderByToken, fetchPage, fetchPageById, fetchPageMeta, fetchPages, fetchProduct, fetchProducts, fetchSiteConfig, fields, formatPrice, fractionDigits, fromMinorUnits, getBlockContentForLanguage, graphqlRequest, isAccessExpired, isDevelopment, isProtocolCompatible, isVerifiedEditUrl, localeForPath, localeForPathname, localesFromSiteConfig, localizeHref, localizeHtmlLinks, localizedPath, normalizeOrigin, normalizeSlug, openSession, parseEditorMessage, postToEditor, resolveApiUrl, resolveEditorOrigin, resolveForms, resolveInitialTarget, resolvePublicUrl, resolveSiteLocales, resolveWorkspaceId, sealSession, sessionCookieOptions, splitCmssyLocale, splitLocaleFromPath, toCspOrigin, toMinorUnits, toSessionPayload, verifyCmssyWebhook };
+export { CMSSY_EDIT_HEADER, CMSSY_EDIT_QUERY_PARAM, CMSSY_LOCALE_HEADER, CMSSY_SECRET_QUERY_PARAM, CMSSY_SESSION_COOKIE, CmssyRequestError, CmssyWebhookError, DEFAULT_CMSSY_API_URL, DEFAULT_CMSSY_EDITOR_ORIGINS, FORM_QUERY, MIN_SESSION_SECRET_LENGTH, MODEL_DEFINITIONS_QUERY, MODEL_RECORDS_QUERY, PRODUCTS_QUERY, PROTOCOL_VERSION, RECORDS_BY_IDS_QUERY, SESSION_MAX_AGE_SECONDS, SITE_CONFIG_QUERY, SUBMIT_FORM_MUTATION, applyCmssyCsp, asBucket, assertAuthConfig, backendAddToCart, backendApplyDiscount, backendCheckout, backendClearCart, backendForgotPassword, backendGetCart, backendMergeCart, backendMyOrder, backendMyOrders, backendOrderByToken, backendProduct, backendRefresh, backendRegister, backendRemoveDiscount, backendRemoveItem, backendResetPassword, backendSetShippingMethod, backendSignIn, backendSignOut, backendSignOutEverywhere, backendUpdateItem, backendVerifyEmail, buildBlockContext, buildLocaleSwitchHref, cachedWorkspaceId, clearWorkspaceIdCache, cmssyCspHeaders, cmssySecretsMatch, collectFormIds, createCmssyClient, decodeAccessClaims, defineCmssyConfig, fetchLayouts, fetchOrderByToken, fetchPage, fetchPageById, fetchPageMeta, fetchPages, fetchProduct, fetchProducts, fetchSiteConfig, fields, formatPrice, fractionDigits, fromMinorUnits, getBlockContentForLanguage, graphqlRequest, isAccessExpired, isDevelopment, isProtocolCompatible, isVerifiedEditUrl, localeForPath, localeForPathname, localesFromSiteConfig, localizeHref, localizeHtmlLinks, localizedPath, normalizeOrigin, normalizeSlug, openSession, parseEditorMessage, postToEditor, resolveApiUrl, resolveEditorOrigin, resolveForms, resolveInitialTarget, resolvePublicUrl, resolveRelationContent, resolveSiteLocales, resolveWorkspaceId, sealSession, sessionCookieOptions, splitCmssyLocale, splitLocaleFromPath, toCspOrigin, toMinorUnits, toSessionPayload, verifyCmssyWebhook };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cmssy/core",
-  "version": "9.4.0",
+  "version": "9.6.0",
   "description": "Framework-agnostic cmssy client: content, commerce, config, editor protocol. No React, no Next.",
   "keywords": [
     "cmssy",
@@ -52,7 +52,7 @@
     "vitest": "^2.1.0"
   },
   "dependencies": {
-    "@cmssy/types": "0.28.0",
+    "@cmssy/types": "0.29.0",
     "jose": "^6.2.3"
   },
   "scripts": {