@riverbankcms/sdk 0.138.0 → 0.139.0

package/dist/_dts/core/src/mailing-list-identifiers.d.ts

@@ -0,0 +1,21 @@
+import type { Brand } from './branded';
+export type NewsletterListId = Brand<string, 'NewsletterListId'>;
+export type MailchimpConnectionId = Brand<string, 'MailchimpConnectionId'>;
+export type MailchimpAccountId = Brand<string, 'MailchimpAccountId'>;
+export type MailchimpAudienceId = Brand<string, 'MailchimpAudienceId'>;
+export type MailchimpInterestId = Brand<string, 'MailchimpInterestId'>;
+export type MailchimpTagName = Brand<string, 'MailchimpTagName'>;
+export type BrevoConnectionId = Brand<string, 'BrevoConnectionId'>;
+export type BrevoAccountId = Brand<string, 'BrevoAccountId'>;
+export type BrevoListId = Brand<number, 'BrevoListId'>;
+export type BrevoConfirmationTemplateId = Brand<number, 'BrevoConfirmationTemplateId'>;
+export declare function parseNewsletterListId(value: unknown): NewsletterListId | null;
+export declare function parseMailchimpConnectionId(value: unknown): MailchimpConnectionId | null;
+export declare function parseMailchimpAccountId(value: unknown): MailchimpAccountId | null;
+export declare function parseMailchimpAudienceId(value: unknown): MailchimpAudienceId | null;
+export declare function parseMailchimpInterestId(value: unknown): MailchimpInterestId | null;
+export declare function parseMailchimpTagName(value: unknown): MailchimpTagName | null;
+export declare function parseBrevoConnectionId(value: unknown): BrevoConnectionId | null;
+export declare function parseBrevoAccountId(value: unknown): BrevoAccountId | null;
+export declare function parseBrevoListId(value: unknown): BrevoListId | null;
+export declare function parseBrevoConfirmationTemplateId(value: unknown): BrevoConfirmationTemplateId | null;

package/dist/_dts/core/src/mailing-list-runtime.d.ts

@@ -0,0 +1,42 @@
+import type { BrevoListId, MailchimpAudienceId, MailchimpInterestId } from './mailing-list-identifiers';
+import { type Result } from './result';
+import type { MailingListGlobalForm, MailingListSetupRevision, NativeMailingListTopicId } from './mailing-list-setup';
+export type MailingListRuntimeContext = Readonly<{
+    tag: 'not_configured';
+}> | Readonly<{
+    tag: 'configured';
+    revision: MailingListSetupRevision;
+    form: MailingListGlobalForm;
+    provider: MailingListRuntimeProvider;
+}>;
+export type MailingListRuntimeProvider = Readonly<{
+    provider: 'native';
+    defaultTopicId: NativeMailingListTopicId;
+    topics: readonly Readonly<{
+        id: NativeMailingListTopicId;
+        name: string;
+    }>[];
+}> | Readonly<{
+    provider: 'brevo';
+    defaultListId: BrevoListId;
+    lists: readonly Readonly<{
+        id: BrevoListId;
+        name: string;
+    }>[];
+}> | Readonly<{
+    provider: 'mailchimp';
+    defaultAudienceId: MailchimpAudienceId;
+    audiences: readonly Readonly<{
+        id: MailchimpAudienceId;
+        name: string;
+        interests: readonly Readonly<{
+            id: MailchimpInterestId;
+            name: string;
+            categoryName: string;
+        }>[];
+    }>[];
+}>;
+export type MailingListRuntimeContextParseError = Readonly<{
+    tag: 'invalid_mailing_list_runtime_context';
+}>;
+export declare function parseMailingListRuntimeContext(value: unknown): Result<MailingListRuntimeContext, MailingListRuntimeContextParseError>;

package/dist/_dts/core/src/mailing-list-setup-parser.d.ts

@@ -0,0 +1,14 @@
+import type { ConfiguredMailingListProvider, MailingListGlobalForm, MailingListSetupRevision, MailingListSiteSetup } from './mailing-list-setup';
+import { type Result } from './result';
+export type MailingListSetupParseError = Readonly<{
+    tag: 'invalid_mailing_list_setup';
+    field: 'shape' | 'tag' | 'siteId' | 'revision' | 'form' | 'provider' | 'connectionId' | 'accountId' | 'defaultTargetId' | 'confirmation';
+}>;
+export type MailingListGlobalFormParseError = Readonly<{
+    tag: 'invalid_mailing_list_global_form';
+    field: 'shape' | 'fields' | 'includeOptionalPhone' | 'buttonLabel' | 'privacyNote';
+}>;
+export declare function parseMailingListGlobalForm(value: unknown): Result<MailingListGlobalForm, MailingListGlobalFormParseError>;
+export declare function parseMailingListSiteSetup(value: unknown): Result<MailingListSiteSetup, MailingListSetupParseError>;
+export declare function parseConfiguredMailingListProvider(value: unknown): Result<ConfiguredMailingListProvider, MailingListSetupParseError>;
+export declare function parseMailingListSetupRevision(value: unknown): MailingListSetupRevision | null;

package/dist/_dts/core/src/mailing-list-setup.d.ts

@@ -0,0 +1,129 @@
+import type { Brand, SiteId } from './branded';
+import type { BrevoAccountId, BrevoConfirmationTemplateId, BrevoConnectionId, BrevoListId, MailchimpAccountId, MailchimpAudienceId, MailchimpConnectionId, NewsletterListId } from './mailing-list-identifiers';
+export type MailingListProvider = 'native' | 'mailchimp' | 'brevo';
+export type NativeMailingListTopicId = NewsletterListId;
+export type MailingListSetupRevision = Brand<number, 'MailingListSetupRevision'>;
+export type MailingListProfileField = 'name' | 'first_name' | 'last_name' | 'company' | 'phone';
+export type MailingListGlobalFields = Readonly<{
+    preset: 'emailOnly';
+}> | Readonly<{
+    preset: 'emailName';
+    name: 'required' | 'optional';
+}> | Readonly<{
+    preset: 'emailFirstLast';
+    firstName: 'required' | 'optional';
+    lastName: 'required' | 'optional';
+}> | Readonly<{
+    preset: 'emailNameCompany';
+    name: 'required' | 'optional';
+    company: 'required' | 'optional';
+}>;
+export type MailingListGlobalForm = Readonly<{
+    fields: MailingListGlobalFields;
+    includeOptionalPhone: boolean;
+    buttonLabel: string;
+    privacyNote: string | null;
+}>;
+export type ToggleConfirmation = Readonly<{
+    tag: 'off';
+}> | Readonly<{
+    tag: 'on';
+}>;
+export type BrevoConfirmation = Readonly<{
+    tag: 'off';
+}> | Readonly<{
+    tag: 'on';
+    templateId: BrevoConfirmationTemplateId;
+    redirectUrl: string;
+}>;
+export type NativeMailingListSetup = Readonly<{
+    provider: 'native';
+    defaultTopicId: NativeMailingListTopicId;
+    confirmation: ToggleConfirmation;
+}>;
+export type MailchimpMailingListSetup = Readonly<{
+    provider: 'mailchimp';
+    connectionId: MailchimpConnectionId;
+    accountId: MailchimpAccountId;
+    defaultAudienceId: MailchimpAudienceId;
+    confirmation: ToggleConfirmation;
+}>;
+export type BrevoMailingListSetup = Readonly<{
+    provider: 'brevo';
+    connectionId: BrevoConnectionId;
+    accountId: BrevoAccountId;
+    defaultListId: BrevoListId;
+    confirmation: BrevoConfirmation;
+}>;
+export type ConfiguredMailingListProvider = NativeMailingListSetup | MailchimpMailingListSetup | BrevoMailingListSetup;
+export type MailingListSiteSetup = Readonly<{
+    tag: 'not_configured';
+    siteId: SiteId;
+}> | Readonly<{
+    tag: 'configured';
+    siteId: SiteId;
+    revision: MailingListSetupRevision;
+    form: MailingListGlobalForm;
+    provider: ConfiguredMailingListProvider;
+}>;
+export type MailingListDestinationFieldRequirements = Readonly<{
+    destinationKey: string;
+    requiredFields: readonly MailingListProfileField[];
+    acceptedFields: readonly MailingListProfileField[];
+}>;
+export type MailingListFieldCompatibilityIssue = Readonly<{
+    tag: 'destination_requires_uncollected_field';
+    destinationKey: string;
+    field: MailingListProfileField;
+}> | Readonly<{
+    tag: 'destination_requires_site_required_field';
+    destinationKey: string;
+    field: MailingListProfileField;
+}> | Readonly<{
+    tag: 'destination_rejects_required_site_field';
+    destinationKey: string;
+    field: MailingListProfileField;
+}> | Readonly<{
+    tag: 'destination_rejects_collected_site_field';
+    destinationKey: string;
+    field: MailingListProfileField;
+}>;
+export type MailingListFieldCompatibilityPlan = Readonly<{
+    tag: 'compatible';
+}> | Readonly<{
+    tag: 'blocked';
+    issues: readonly [
+        MailingListFieldCompatibilityIssue,
+        ...MailingListFieldCompatibilityIssue[]
+    ];
+}>;
+export declare function planMailingListFieldCompatibility(input: Readonly<{
+    form: MailingListGlobalForm;
+    destinations: readonly MailingListDestinationFieldRequirements[];
+}>): MailingListFieldCompatibilityPlan;
+export type MailingListSetupSwitchPlan = Readonly<{
+    tag: 'activate';
+    affectedPlacementCount: 0;
+}> | Readonly<{
+    tag: 'update_same_scope';
+    affectedPlacementCount: number;
+}> | Readonly<{
+    tag: 'replace_scope';
+    affectedPlacementCount: number;
+}>;
+export declare function planMailingListSetupSwitch(input: Readonly<{
+    previousScope: MailingListProviderScope | null;
+    nextScope: MailingListProviderScope;
+    placementModes: readonly ('default' | 'custom')[];
+    defaultChanged: boolean;
+}>): MailingListSetupSwitchPlan;
+export type MailingListProviderScope = Readonly<{
+    provider: 'native';
+}> | Readonly<{
+    provider: 'mailchimp';
+    accountId: MailchimpAccountId;
+}> | Readonly<{
+    provider: 'brevo';
+    accountId: BrevoAccountId;
+}>;
+export declare function countDefaultMailingListPlacements(placementModes: readonly ('default' | 'custom')[]): number;

package/dist/_dts/core/src/mailing-list-submission.d.ts

@@ -0,0 +1,244 @@
+import { type Brand, type ContentVersionId, type SiteId } from './branded';
+import type { FooterModuleId } from './footer-composition-types';
+import type { BrevoConfirmation, MailingListGlobalForm, MailingListProvider, MailingListSetupRevision, ToggleConfirmation } from './mailing-list-setup';
+import type { ResolvedMailingListTarget } from './mailing-list-targeting';
+import type { BrevoConnectionId, MailchimpConnectionId } from './mailing-list-identifiers';
+export declare const MAILING_LIST_SUBMISSION_BUDGET_MS = 10000;
+export type MailingListBlockId = Brand<string, 'MailingListBlockId'>;
+export type MailingListSignedSourceToken = Brand<string, 'MailingListSignedSourceToken'>;
+export type MailingListSdkFooterBlockId = Brand<string, 'MailingListSdkFooterBlockId'>;
+export type MailingListSdkContentHash = Brand<string, 'MailingListSdkContentHash'>;
+export type MailingListFooterRevision = Brand<number, 'MailingListFooterRevision'>;
+export type ExternalSignupConsentId = Brand<string, 'ExternalSignupConsentId'>;
+export type NormalizedSubscriberEmail = Brand<string, 'NormalizedSubscriberEmail'>;
+export declare function parseMailingListBlockId(value: unknown): MailingListBlockId | null;
+export declare function parseMailingListSignedSourceToken(value: unknown): MailingListSignedSourceToken | null;
+export declare function parseMailingListSdkFooterBlockId(value: unknown): MailingListSdkFooterBlockId | null;
+export declare function parseMailingListSdkContentHash(value: unknown): MailingListSdkContentHash | null;
+export declare function parseMailingListContentVersionId(value: unknown): ContentVersionId | null;
+export declare function parseMailingListFooterRevision(value: unknown): MailingListFooterRevision | null;
+export type MailingListSignupSource = Readonly<{
+    tag: 'published_block';
+    blockId: MailingListBlockId;
+    contentVersionId: ContentVersionId;
+}> | Readonly<{
+    tag: 'applied_footer';
+    sectionId: FooterModuleId;
+    revision: MailingListFooterRevision;
+}> | Readonly<{
+    tag: 'sdk_footer_block';
+    blockId: MailingListSdkFooterBlockId;
+    contentHash: MailingListSdkContentHash;
+}>;
+/** Public proof of which published placement owns a signup request. */
+export type MailingListSignupSourceRef = Readonly<{
+    tag: 'block_ref';
+    blockId: MailingListBlockId;
+}> | Readonly<{
+    tag: 'signed_source_ref';
+    token: MailingListSignedSourceToken;
+}>;
+/** Source identity signed into managed-footer and SDK-footer form tokens. */
+export type MailingListSignupTokenSource = Readonly<{
+    kind: 'block';
+    blockId: MailingListBlockId;
+}> | Readonly<{
+    kind: 'footer-composition';
+    sectionId: FooterModuleId;
+}> | Readonly<{
+    kind: 'sdk-footer-block';
+    blockId: MailingListSdkFooterBlockId;
+    contentHash: MailingListSdkContentHash;
+}>;
+export declare function buildMailingListSignupBlockSourceRef(blockId: unknown): MailingListSignupSourceRef | null;
+type MailingListSignupProfileBase = Readonly<{
+    email: NormalizedSubscriberEmail;
+    phone: Readonly<{
+        tag: 'not_collected';
+    }> | Readonly<{
+        tag: 'collected';
+        value: string | null;
+    }>;
+}>;
+export type ResolvedMailingListProfileField = Readonly<{
+    requirement: 'required';
+    value: string;
+}> | Readonly<{
+    requirement: 'optional';
+    value: string | null;
+}>;
+export type MailingListSignupProfile = (MailingListSignupProfileBase & Readonly<{
+    preset: 'emailOnly';
+}>) | (MailingListSignupProfileBase & Readonly<{
+    preset: 'emailName';
+    name: ResolvedMailingListProfileField;
+}>) | (MailingListSignupProfileBase & Readonly<{
+    preset: 'emailFirstLast';
+    firstName: ResolvedMailingListProfileField;
+    lastName: ResolvedMailingListProfileField;
+}>) | (MailingListSignupProfileBase & Readonly<{
+    preset: 'emailNameCompany';
+    name: ResolvedMailingListProfileField;
+    company: ResolvedMailingListProfileField;
+}>);
+export type MailingListSignupProfileInput = Readonly<{
+    email: string;
+    name?: string | null;
+    firstName?: string | null;
+    lastName?: string | null;
+    company?: string | null;
+    phone?: string | null;
+}>;
+export type MailingListSignupProfileParseError = Readonly<{
+    tag: 'invalid_email';
+}> | Readonly<{
+    tag: 'required_field_missing';
+    field: 'name' | 'first_name' | 'last_name' | 'company';
+}>;
+export declare function parseMailingListSignupProfile(form: MailingListGlobalForm, input: MailingListSignupProfileInput): Readonly<{
+    ok: true;
+    value: MailingListSignupProfile;
+}> | Readonly<{
+    ok: false;
+    error: MailingListSignupProfileParseError;
+}>;
+type ResolvedMailingListSignupIntentBase = Readonly<{
+    siteId: SiteId;
+    setupRevision: MailingListSetupRevision;
+    source: MailingListSignupSource;
+    consentedAt: string;
+}>;
+type ResolvedMailingListFormProfile = Readonly<{
+    formPreset: 'emailOnly';
+    profile: Extract<MailingListSignupProfile, {
+        preset: 'emailOnly';
+    }>;
+}> | Readonly<{
+    formPreset: 'emailName';
+    profile: Extract<MailingListSignupProfile, {
+        preset: 'emailName';
+    }>;
+}> | Readonly<{
+    formPreset: 'emailFirstLast';
+    profile: Extract<MailingListSignupProfile, {
+        preset: 'emailFirstLast';
+    }>;
+}> | Readonly<{
+    formPreset: 'emailNameCompany';
+    profile: Extract<MailingListSignupProfile, {
+        preset: 'emailNameCompany';
+    }>;
+}>;
+type ResolvedMailingListProviderIntent = Readonly<{
+    provider: 'native';
+    target: Extract<ResolvedMailingListTarget, {
+        provider: 'native';
+    }>;
+    confirmation: ToggleConfirmation;
+}> | Readonly<{
+    provider: 'mailchimp';
+    connectionId: MailchimpConnectionId;
+    target: Extract<ResolvedMailingListTarget, {
+        provider: 'mailchimp';
+    }>;
+    confirmation: ToggleConfirmation;
+}> | Readonly<{
+    provider: 'brevo';
+    connectionId: BrevoConnectionId;
+    target: Extract<ResolvedMailingListTarget, {
+        provider: 'brevo';
+    }>;
+    confirmation: BrevoConfirmation;
+}>;
+export type ResolvedMailingListSignupIntent = ResolvedMailingListSignupIntentBase & ResolvedMailingListFormProfile & ResolvedMailingListProviderIntent;
+export type MailingListProviderAcknowledgement = Readonly<{
+    tag: 'subscribed';
+}> | Readonly<{
+    tag: 'confirmation_requested';
+}>;
+export type MailingListProviderFailure = Readonly<{
+    tag: 'configuration_unavailable';
+}> | Readonly<{
+    tag: 'authentication_failed';
+}> | Readonly<{
+    tag: 'target_unavailable';
+}> | Readonly<{
+    tag: 'profile_rejected';
+}> | Readonly<{
+    tag: 'subscriber_suppressed';
+}> | Readonly<{
+    tag: 'rate_limited';
+}> | Readonly<{
+    tag: 'temporarily_unavailable';
+}> | Readonly<{
+    tag: 'uncertain';
+    reason: 'deadline_exceeded' | 'network_interrupted';
+}>;
+export type MailingListProviderSubmissionResult = Readonly<{
+    ok: true;
+    acknowledgement: MailingListProviderAcknowledgement;
+}> | Readonly<{
+    ok: false;
+    error: MailingListProviderFailure;
+}>;
+export type MailingListSubmissionDeadline = Readonly<{
+    deadlineEpochMs: number;
+    signal: AbortSignal;
+}>;
+export type MailingListProviderPort<TProvider extends MailingListProvider> = Readonly<{
+    submit: (intent: Extract<ResolvedMailingListSignupIntent, {
+        provider: TProvider;
+    }>, deadline: MailingListSubmissionDeadline) => Promise<MailingListProviderSubmissionResult>;
+}>;
+export type MailingListPublicSignupResponse = Readonly<{
+    tag: 'subscribed';
+}> | Readonly<{
+    tag: 'confirmation_required';
+}> | Readonly<{
+    tag: 'invalid_input';
+    reason: 'profile_rejected';
+}> | Readonly<{
+    tag: 'unavailable';
+    reason: 'configuration_unavailable' | 'stale_configuration' | 'authentication_failed' | 'target_unavailable' | 'subscriber_suppressed' | 'rate_limited' | 'temporarily_unavailable';
+}> | Readonly<{
+    tag: 'uncertain';
+    reason: 'deadline_exceeded' | 'network_interrupted';
+}>;
+export declare function toMailingListPublicSignupResponse(result: MailingListProviderSubmissionResult): MailingListPublicSignupResponse;
+export type ExternalSignupConsentAttemptOutcome = Readonly<{
+    tag: 'consent_recorded';
+}> | Readonly<{
+    tag: 'provider_acknowledged';
+    acknowledgement: MailingListProviderAcknowledgement;
+}> | Readonly<{
+    tag: 'provider_failed';
+    failure: MailingListProviderFailure;
+}>;
+type ExternalSignupConsentRecordBase = Readonly<{
+    id: ExternalSignupConsentId;
+    siteId: SiteId;
+    normalizedEmail: NormalizedSubscriberEmail;
+    consentedAt: string;
+    source: MailingListSignupSource;
+    setupRevision: MailingListSetupRevision;
+    ipAddress: string | null;
+    userAgent: string | null;
+    referer: string | null;
+    outcome: ExternalSignupConsentAttemptOutcome;
+}>;
+export type ExternalSignupConsentRecord = (ExternalSignupConsentRecordBase & Readonly<{
+    provider: 'mailchimp';
+    connectionId: MailchimpConnectionId;
+    target: Extract<ResolvedMailingListTarget, {
+        provider: 'mailchimp';
+    }>;
+    confirmation: ToggleConfirmation;
+}>) | (ExternalSignupConsentRecordBase & Readonly<{
+    provider: 'brevo';
+    connectionId: BrevoConnectionId;
+    target: Extract<ResolvedMailingListTarget, {
+        provider: 'brevo';
+    }>;
+    confirmation: BrevoConfirmation;
+}>);
+export {};

package/dist/_dts/core/src/mailing-list-targeting-parser.d.ts

@@ -0,0 +1,12 @@
+import type { MailingListPlacementTargeting, MailingListVisitorSelection } from './mailing-list-targeting';
+import { type Result } from './result';
+export type MailingListTargetingParseError = Readonly<{
+    tag: 'invalid_mailing_list_targeting';
+    field: 'shape' | 'mode' | 'provider' | 'selection' | 'audienceId' | 'targets' | 'duplicate_target';
+}>;
+export type MailingListVisitorSelectionParseError = Readonly<{
+    tag: 'invalid_mailing_list_visitor_selection';
+    field: 'shape' | 'provider' | 'targets';
+}>;
+export declare function parseMailingListPlacementTargeting(value: unknown): Result<MailingListPlacementTargeting, MailingListTargetingParseError>;
+export declare function parseMailingListVisitorSelection(value: unknown): Result<MailingListVisitorSelection, MailingListVisitorSelectionParseError>;

package/dist/_dts/core/src/mailing-list-targeting.d.ts

@@ -0,0 +1,93 @@
+import type { ReadonlyNonEmptyArray } from './non-empty-array';
+import type { BrevoListId, MailchimpInterestId, MailchimpAudienceId } from './mailing-list-identifiers';
+import type { ConfiguredMailingListProvider, MailingListProvider, NativeMailingListTopicId } from './mailing-list-setup';
+import { type Result } from './result';
+export type MailingListDefaultTargeting = Readonly<{
+    mode: 'default';
+}>;
+export type NativeMailingListCustomTargeting = Readonly<{
+    mode: 'custom';
+    provider: 'native';
+    selection: Readonly<{
+        tag: 'fixed';
+        topicIds: ReadonlyNonEmptyArray<NativeMailingListTopicId>;
+    }> | Readonly<{
+        tag: 'visitor_choice';
+        offeredTopicIds: ReadonlyNonEmptyArray<NativeMailingListTopicId>;
+    }>;
+}>;
+export type BrevoMailingListCustomTargeting = Readonly<{
+    mode: 'custom';
+    provider: 'brevo';
+    selection: Readonly<{
+        tag: 'fixed';
+        listIds: ReadonlyNonEmptyArray<BrevoListId>;
+    }> | Readonly<{
+        tag: 'visitor_choice';
+        offeredListIds: ReadonlyNonEmptyArray<BrevoListId>;
+    }>;
+}>;
+export type MailchimpMailingListCustomTargeting = Readonly<{
+    mode: 'custom';
+    provider: 'mailchimp';
+    audienceId: MailchimpAudienceId;
+    selection: Readonly<{
+        tag: 'fixed';
+        interestIds: readonly MailchimpInterestId[];
+    }> | Readonly<{
+        tag: 'visitor_choice';
+        offeredInterestIds: ReadonlyNonEmptyArray<MailchimpInterestId>;
+    }>;
+}>;
+export type MailingListPlacementTargeting = MailingListDefaultTargeting | NativeMailingListCustomTargeting | BrevoMailingListCustomTargeting | MailchimpMailingListCustomTargeting;
+export declare function sameMailingListPlacementTargeting(left: MailingListPlacementTargeting, right: MailingListPlacementTargeting): boolean;
+export type MailingListVisitorSelection = Readonly<{
+    provider: 'native';
+    topicIds: readonly NativeMailingListTopicId[];
+}> | Readonly<{
+    provider: 'brevo';
+    listIds: readonly BrevoListId[];
+}> | Readonly<{
+    provider: 'mailchimp';
+    interestIds: readonly MailchimpInterestId[];
+}>;
+export type ResolvedMailingListTarget = Readonly<{
+    provider: 'native';
+    topicIds: ReadonlyNonEmptyArray<NativeMailingListTopicId>;
+}> | Readonly<{
+    provider: 'brevo';
+    listIds: ReadonlyNonEmptyArray<BrevoListId>;
+}> | Readonly<{
+    provider: 'mailchimp';
+    audienceId: MailchimpAudienceId;
+    interestIds: readonly MailchimpInterestId[];
+}>;
+export type MailingListTargetResolutionError = Readonly<{
+    tag: 'targeting_provider_mismatch';
+    setupProvider: MailingListProvider;
+    targetingProvider: MailingListProvider;
+}> | Readonly<{
+    tag: 'visitor_selection_not_allowed';
+}> | Readonly<{
+    tag: 'visitor_selection_required';
+}> | Readonly<{
+    tag: 'visitor_selection_provider_mismatch';
+}> | Readonly<{
+    tag: 'visitor_selection_outside_offer';
+}>;
+export declare function resolveMailingListTarget(input: Readonly<{
+    setup: ConfiguredMailingListProvider;
+    targeting: MailingListPlacementTargeting;
+    visitorSelection?: MailingListVisitorSelection;
+}>): Result<ResolvedMailingListTarget, MailingListTargetResolutionError>;
+export type MailingListChoicePresentation = Readonly<{
+    tag: 'hidden';
+}> | Readonly<{
+    tag: 'automatic';
+    selection: MailingListVisitorSelection;
+}> | Readonly<{
+    tag: 'visitor_choice';
+    provider: MailingListProvider;
+    optionCount: number;
+}>;
+export declare function planMailingListChoicePresentation(targeting: MailingListPlacementTargeting): MailingListChoicePresentation;

package/dist/_dts/core/src/navigation-locations.d.ts

@@ -0,0 +1,28 @@
+import { type Result } from './result';
+/** The only places a site's navigation can be displayed. */
+export declare const NAVIGATION_LOCATIONS: readonly ["main", "footer", "legal"];
+export type NavigationLocation = (typeof NAVIGATION_LOCATIONS)[number];
+export type NavigationLocationDescriptor = Readonly<{
+    location: NavigationLocation;
+    label: string;
+    description: string;
+}>;
+export declare const NAVIGATION_LOCATION_DESCRIPTORS: Readonly<Record<NavigationLocation, NavigationLocationDescriptor>>;
+export type SiteNavigationLocationRow<T = unknown> = Readonly<{
+    location: unknown;
+    value: T;
+}>;
+export type SiteNavigationLocationsError = Readonly<{
+    kind: 'invalid_location';
+    index: number;
+    value: unknown;
+}> | Readonly<{
+    kind: 'duplicate_location';
+    location: NavigationLocation;
+}> | Readonly<{
+    kind: 'missing_location';
+    location: NavigationLocation;
+}>;
+export type SiteNavigationLocations<T> = Readonly<Record<NavigationLocation, T>>;
+/** Parse all rows for one site into a complete fixed-location record. */
+export declare function parseSiteNavigationLocations<T>(rows: readonly SiteNavigationLocationRow<T>[]): Result<SiteNavigationLocations<T>, SiteNavigationLocationsError>;

package/dist/_dts/core/src/public-profile.d.ts

@@ -55,13 +55,21 @@ export type PublicSocialLink = Readonly<{
     label: string;
     url: string;
 }>;
+/**
+ * Whether the site shows its business address publicly. Absent on every
+ * profile saved before this field existed, and the footer has always shown
+ * the address whenever its composition selected one, so absent reads as
+ * `shown`.
+ */
+export type PublicAddressVisibility = 'shown' | 'hidden';
 export type PublicProfile = Readonly<{
     contact: PublicContactDetails | null;
     openingHours: WeeklyOpeningHours | null;
     socialLinks: readonly PublicSocialLink[];
+    addressVisibility: PublicAddressVisibility;
 }>;
 export type PublicProfileParseError = Readonly<{
-    code: 'invalid_shape' | 'contact_method_required' | 'invalid_email' | 'invalid_phone' | 'invalid_timezone' | 'invalid_weekdays' | 'invalid_time' | 'invalid_interval' | 'overlapping_intervals' | 'invalid_social_link' | 'duplicate_social_link_id';
+    code: 'invalid_shape' | 'contact_method_required' | 'invalid_email' | 'invalid_phone' | 'invalid_timezone' | 'invalid_weekdays' | 'invalid_time' | 'invalid_interval' | 'overlapping_intervals' | 'invalid_social_link' | 'invalid_address_visibility' | 'duplicate_social_link_id';
     path: string;
     message: string;
 }>;

package/dist/_dts/core/src/public-read-cache-contract.d.ts

@@ -0,0 +1,45 @@
+export type PublicReadEndpoint = 'listPublishedEntries' | 'getPublishedEntryPreview' | 'listPublicEvents' | 'listPublicEventCalendarWindow' | 'listPublicRecurringSchedule' | 'getPublicEventDetails' | 'resolveEventSubroute' | 'listPublicRouteCandidates' | 'listPublicTeamMembers' | 'listPublicProducts' | 'listPublicPasses' | 'listPublicMemberships' | 'getPublicFormById' | 'getPublicBookingServices' | 'getPublicBookingService' | 'getPublicBookingResourcesReference' | 'getPublicBookingAvailableDates' | 'getPublicBookingAvailableSlots' | 'getPublicWeeklySlotAvailability' | 'listPublicForms' | 'checkRedirect' | 'getPublicRoutableContent' | 'getPublicSitemapRoutes';
+export type PublicReadCacheTagKind = 'published_content' | 'public_team_members' | 'public_products' | 'site_forms';
+export type PublicReadTransport = 'direct' | 'batch_only';
+export type PublicReadCachePolicy = Readonly<{
+    kind: 'live';
+    reason: 'booking_correctness';
+    freshness: 'availability';
+    transport: PublicReadTransport;
+}> | Readonly<{
+    kind: 'tagged';
+    tags: readonly PublicReadCacheTagKind[];
+    freshness: 'content';
+    transport: PublicReadTransport;
+}>;
+export declare const PUBLIC_AVAILABILITY_FRESHNESS_SECONDS = 60;
+export declare const PUBLIC_CONTENT_FRESHNESS_SECONDS = 3600;
+/** The single classification authority for cacheable public reads. */
+export declare const PUBLIC_READ_CACHE_POLICIES: {
+    readonly listPublishedEntries: PublicReadCachePolicy;
+    readonly getPublishedEntryPreview: PublicReadCachePolicy;
+    readonly listPublicEvents: PublicReadCachePolicy;
+    readonly listPublicEventCalendarWindow: PublicReadCachePolicy;
+    readonly listPublicRecurringSchedule: PublicReadCachePolicy;
+    readonly getPublicEventDetails: PublicReadCachePolicy;
+    readonly resolveEventSubroute: PublicReadCachePolicy;
+    readonly listPublicRouteCandidates: PublicReadCachePolicy;
+    readonly listPublicTeamMembers: PublicReadCachePolicy;
+    readonly listPublicProducts: PublicReadCachePolicy;
+    readonly listPublicPasses: PublicReadCachePolicy;
+    readonly listPublicMemberships: PublicReadCachePolicy;
+    readonly getPublicFormById: PublicReadCachePolicy;
+    readonly getPublicBookingServices: PublicReadCachePolicy;
+    readonly getPublicBookingService: PublicReadCachePolicy;
+    readonly getPublicBookingResourcesReference: PublicReadCachePolicy;
+    readonly getPublicBookingAvailableDates: PublicReadCachePolicy;
+    readonly getPublicBookingAvailableSlots: PublicReadCachePolicy;
+    readonly getPublicWeeklySlotAvailability: PublicReadCachePolicy;
+    readonly listPublicForms: PublicReadCachePolicy;
+    readonly checkRedirect: PublicReadCachePolicy;
+    readonly getPublicRoutableContent: PublicReadCachePolicy;
+    readonly getPublicSitemapRoutes: PublicReadCachePolicy;
+};
+export declare function isPublicReadEndpoint(endpoint: string): endpoint is PublicReadEndpoint;
+export declare function getPublicReadCachePolicy(endpoint: PublicReadEndpoint): PublicReadCachePolicy;
+export declare function publicReadFreshnessSeconds(endpoint: PublicReadEndpoint): number;