@sonordev/contracts 2.13.0 → 2.16.0

package/dist/funnels.d.ts

@@ -0,0 +1,576 @@
+import { type PublicationColors } from './publication-branding';
+export { normalizeCampaignSlug } from './campaign-normalize';
+export declare const FUNNEL_SCHEMA_VERSION: 1;
+export declare const MANAGED_FUNNEL_PATH_PREFIX: '/f';
+export declare const FUNNEL_TEMPLATES: readonly ['newsletter', 'requested_guide', 'inquiry'];
+export type FunnelTemplate = typeof FUNNEL_TEMPLATES[number];
+export type FunnelLifecycle = 'draft' | 'active' | 'paused';
+export type FunnelHealth = 'healthy' | 'waiting' | 'needs_attention' | 'unknown';
+export type FunnelBodyBlock = {
+    type: 'paragraph';
+    text: string;
+} | {
+    type: 'bullets';
+    items: string[];
+};
+export interface FunnelBrandPresentation {
+    displayName: string;
+    tagline: string;
+    fullLogoUrl: string | null;
+    squareLogoUrl: string | null;
+    colors: Required<PublicationColors>;
+    typography: {
+        headingFamily: string;
+        bodyFamily: string;
+    };
+    scheme: 'light' | 'dark';
+}
+export interface FunnelBrandOverride {
+    displayName?: string | null;
+    tagline?: string | null;
+    fullLogoAssetId?: string | null;
+    squareLogoAssetId?: string | null;
+    colors?: {
+        [K in keyof PublicationColors]?: string | null;
+    };
+    typography?: {
+        headingFamily?: string | null;
+        bodyFamily?: string | null;
+    };
+}
+export type FunnelBrandSource = 'project' | 'brand_profile' | 'site_design' | 'publication_branding' | 'platforms.publication' | 'platforms.email' | 'funnel_override' | 'default';
+export interface FunnelBrandSnapshot {
+    page: FunnelBrandPresentation;
+    email: FunnelBrandPresentation;
+    provenance: Record<string, FunnelBrandSource>;
+    assetRefs: {
+        id: string | null;
+        version: string | null;
+    }[];
+    capturedAt: string;
+    fingerprint: string;
+}
+export type FunnelStep = {
+    id: string;
+    type: 'wait';
+    durationSeconds: number;
+} | {
+    id: string;
+    type: 'send_email';
+    templateId: string;
+    purpose: 'requested_fulfillment' | 'marketing';
+    guideAssetId?: string | null;
+} | {
+    id: string;
+    type: 'add_tag';
+    target: 'subscriber';
+    tag: string;
+} | {
+    id: string;
+    type: 'create_task';
+    ownerContactId: string;
+    title: string;
+    dueAfterSeconds: number;
+};
+export interface FunnelDefinition {
+    schemaVersion: 1;
+    name: string;
+    template: FunnelTemplate;
+    site: string;
+    entry: {
+        formId: string;
+        mode: 'future_accepted_form_only';
+    };
+    goal: {
+        type: 'newsletter_confirmed' | 'guide_requested' | 'inquiry_received' | 'booking_confirmed';
+        bookingTypeId?: string | null;
+    };
+    page: {
+        mode: 'existing' | 'managed';
+        path: string;
+        slug?: string | null;
+        headline: string;
+        body: FunnelBodyBlock[];
+        formId: string;
+        offerAssetId?: string | null;
+    };
+    permission: {
+        mode: 'requested_only' | 'marketing_opt_in';
+        optInFieldSlug?: string | null;
+    };
+    brandOverride?: FunnelBrandOverride;
+    steps: FunnelStep[];
+    exits: {
+        unsubscribe: true;
+        manualStop: true;
+        confirmedBooking?: {
+            enabled: boolean;
+            bookingTypeId: string | null;
+        };
+    };
+}
+export interface FunnelIssue {
+    code: string;
+    path: string;
+    message: string;
+    fixRef?: {
+        section: string;
+        field?: string;
+        resourceId?: string;
+    };
+}
+export interface FunnelReadiness {
+    definitionRevision: number;
+    brandFingerprint: string;
+    resourceFingerprint: string;
+    ready: boolean;
+    blockers: FunnelIssue[];
+    warnings: FunnelIssue[];
+    capabilities: {
+        managedPage: boolean;
+    };
+}
+export interface PublishedFunnelPage {
+    schemaVersion: 1;
+    id: string;
+    versionId: string;
+    revision: number;
+    site: string;
+    path: string;
+    content: {
+        headline: string;
+        body: FunnelBodyBlock[];
+        offer?: {
+            label: string;
+            href: string;
+        };
+    };
+    brand: FunnelBrandPresentation;
+    conversion: {
+        formSlug: string;
+    };
+    tracking: {
+        campaignSlug: string;
+    };
+}
+export interface FunnelOperationReceipt {
+    operationId: string;
+    projectId: string;
+    orgId: string;
+    funnelId: string;
+    operation: 'create' | 'update' | 'launch' | 'pause' | 'resume' | 'retry' | 'rollback';
+    idempotencyKey: string;
+    requestDigest: string;
+    versionId: string | null;
+    lifecycle: FunnelLifecycle;
+    replayed: boolean;
+    armedFutureEntrantsOnly: true;
+    enrolledExisting: 0;
+    messagesSent: 0;
+    pagePublication: 'not_requested' | 'published' | 'revalidation_pending';
+    health: FunnelHealth;
+    revision: number;
+    commandState: 'committed';
+    funnel: FunnelDetail | null;
+    actor: string;
+    armedAt: string | null;
+    effectScope: 'configuration_only' | 'safe_retry_armed';
+    target: FunnelCommandTarget;
+    ledgerProposalId: string;
+}
+export interface FunnelCommandTarget {
+    funnelId: string | null;
+    enrollmentId: string | null;
+    executionId: string | null;
+    targetVersionId: string | null;
+}
+export interface FunnelLaunchArgs {
+    expectedRevision: number;
+    previewId: string;
+    idempotencyKey: string;
+    confirm: true;
+}
+export interface FunnelLifecycleArgs {
+    expectedActiveVersionId: string;
+    idempotencyKey: string;
+    confirm: true;
+    targetVersionId?: string;
+}
+/** Small closed JSON-schema vocabulary shared by the exported schema and its runtime parser. */
+type Shape = {
+    type?: 'object' | 'array' | 'string' | 'integer' | 'boolean' | 'null';
+    properties?: Record<string, Shape>;
+    required?: readonly string[];
+    additionalProperties?: false;
+    items?: Shape;
+    minItems?: number;
+    maxItems?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    minimum?: number;
+    maximum?: number;
+    enum?: readonly unknown[];
+    const?: unknown;
+    oneOf?: readonly Shape[];
+};
+export type FunnelDraftStep = Extract<FunnelStep, {
+    type: 'wait' | 'add_tag';
+}> | (Omit<Extract<FunnelStep, {
+    type: 'send_email';
+}>, 'templateId' | 'guideAssetId'> & {
+    templateId: string | null;
+    guideAssetId?: string | null;
+}) | (Omit<Extract<FunnelStep, {
+    type: 'create_task';
+}>, 'ownerContactId'> & {
+    ownerContactId: string | null;
+});
+export interface FunnelDraftDefinition extends Omit<FunnelDefinition, 'site' | 'entry' | 'page' | 'steps'> {
+    site: string | null;
+    entry: {
+        formId: string | null;
+        mode: 'future_accepted_form_only';
+    };
+    page: Omit<FunnelDefinition['page'], 'path' | 'formId'> & {
+        path: string | null;
+        formId: string | null;
+    };
+    steps: FunnelDraftStep[];
+}
+export declare const FUNNEL_DRAFT_DEFINITION_JSON_SCHEMA: {
+    readonly type?: 'object' | 'array' | 'string' | 'integer' | 'boolean' | 'null';
+    readonly properties?: Record<string, Shape>;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: false;
+    readonly items?: Shape;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly pattern?: string;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly enum?: readonly unknown[];
+    readonly const?: unknown;
+    readonly oneOf?: readonly Shape[];
+    readonly $schema: 'http://json-schema.org/draft-07/schema#';
+};
+export declare function parseFunnelDraftDefinition(value: unknown): FunnelDraftDefinition;
+export declare function createFunnelDraft(template: FunnelTemplate): FunnelDraftDefinition;
+export declare const FUNNEL_DEFINITION_JSON_SCHEMA: {
+    readonly type?: 'object' | 'array' | 'string' | 'integer' | 'boolean' | 'null';
+    readonly properties?: Record<string, Shape>;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: false;
+    readonly items?: Shape;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly pattern?: string;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly enum?: readonly unknown[];
+    readonly const?: unknown;
+    readonly oneOf?: readonly Shape[];
+    readonly $schema: 'http://json-schema.org/draft-07/schema#';
+};
+export declare const PUBLISHED_FUNNEL_PAGE_JSON_SCHEMA: {
+    readonly type?: 'object' | 'array' | 'string' | 'integer' | 'boolean' | 'null';
+    readonly properties?: Record<string, Shape>;
+    readonly required?: readonly string[];
+    readonly additionalProperties?: false;
+    readonly items?: Shape;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly pattern?: string;
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly enum?: readonly unknown[];
+    readonly const?: unknown;
+    readonly oneOf?: readonly Shape[];
+    readonly $schema: 'http://json-schema.org/draft-07/schema#';
+};
+export declare const FUNNEL_LAUNCH_JSON_SCHEMA: Shape;
+export declare const FUNNEL_LIFECYCLE_JSON_SCHEMA: Shape;
+export declare const FUNNEL_ROLLBACK_JSON_SCHEMA: Shape;
+export declare class FunnelValidationError extends Error {
+    readonly path: string;
+    constructor(path: string, reason: string);
+}
+/** No DNS/network access. Consumers fetching URLs still enforce their connection policy. */
+export declare function isSafeFunnelPublicUrl(value: string): boolean;
+export declare function managedFunnelPath(value: string): string;
+export declare function parseFunnelDefinition(value: unknown): FunnelDefinition;
+export declare function parsePublishedFunnelPage(value: unknown): PublishedFunnelPage;
+export declare function parseFunnelLaunchArgs(value: unknown): FunnelLaunchArgs;
+export declare function parseFunnelLifecycleArgs(value: unknown, operation?: 'pause' | 'resume' | 'rollback'): FunnelLifecycleArgs;
+/** Apply presentation-only overrides to an already resolved canonical brand. Null means inherit. */
+export declare function applyFunnelBrandOverride(inherited: FunnelBrandPresentation, patch?: FunnelBrandOverride, resolvedAssets?: Record<string, {
+    url: string;
+    version?: string;
+}>): {
+    brand: FunnelBrandPresentation;
+    overridePaths: string[];
+    assetRefs: {
+        id: string;
+        version: string | null;
+    }[];
+};
+export interface FunnelCreateArgs {
+    idempotencyKey: string;
+    definition: FunnelDraftDefinition;
+}
+export interface FunnelUpdateArgs extends FunnelCreateArgs {
+    expectedRevision: number;
+}
+export declare const FUNNEL_CREATE_JSON_SCHEMA: Shape;
+export declare const FUNNEL_UPDATE_JSON_SCHEMA: Shape;
+export declare function parseFunnelCreateArgs(value: unknown): FunnelCreateArgs;
+export declare function parseFunnelUpdateArgs(value: unknown): FunnelUpdateArgs;
+export interface FunnelPreview {
+    previewId: string;
+    versionId: string;
+    expiresAt: string;
+    definitionRevision: number;
+    brand: FunnelBrandSnapshot;
+    readiness: FunnelReadiness;
+    page: PublishedFunnelPage | null;
+    launchEvidence: FunnelLaunchEvidence;
+    emailPreviews: {
+        stepId: string;
+        ready: boolean;
+        subject: string | null;
+        contentHtml: string | null;
+        issues: FunnelIssue[];
+    }[];
+}
+export interface FunnelSummary {
+    id: string;
+    name: string;
+    template: FunnelTemplate;
+    site: string | null;
+    revision: number;
+    activeVersionId: string | null;
+    lifecycle: FunnelLifecycle;
+    health: FunnelHealth;
+    hasDraftChanges: boolean;
+    counts: {
+        entered: number;
+        waiting: number;
+        running: number;
+        completed: number;
+        exited: number;
+        needsAttention: number;
+    };
+    countsBasis: 'all_versions_all_time';
+    lastEventAt: string | null;
+}
+export type FunnelDraftArgs = FunnelCreateArgs | FunnelUpdateArgs;
+/** Select create/update explicitly at the HTTP boundary; a missing revision never downgrades an update. */
+export declare function parseFunnelDraftArgs(value: unknown, mode: 'create' | 'update'): FunnelDraftArgs;
+export interface FunnelRevisionArgs {
+    expectedRevision: number;
+}
+export interface FunnelRetryArgs {
+    expectedAttempt: number;
+    idempotencyKey: string;
+    confirm: true;
+}
+export declare const FUNNEL_REVISION_JSON_SCHEMA: Shape;
+export declare const FUNNEL_RETRY_JSON_SCHEMA: Shape;
+export declare const FUNNEL_DRAFT_JSON_SCHEMAS: {
+    readonly create: Shape;
+    readonly update: Shape;
+};
+export declare function parseFunnelRevisionArgs(value: unknown): FunnelRevisionArgs;
+export declare function parseFunnelRetryArgs(value: unknown): FunnelRetryArgs;
+export declare const FUNNEL_READINESS_JSON_SCHEMA: Shape;
+export declare function parseFunnelReadiness(value: unknown): FunnelReadiness;
+export interface FunnelDetail {
+    id: string;
+    revision: number;
+    definition: FunnelDraftDefinition;
+    activeVersionId: string | null;
+    lifecycle: FunnelLifecycle;
+    health: FunnelHealth;
+    hasDraftChanges: boolean;
+    readiness: FunnelReadiness;
+}
+export declare const FUNNEL_DETAIL_JSON_SCHEMA: Shape;
+export declare function parseFunnelDetail(value: unknown): FunnelDetail;
+export declare const FUNNEL_OPERATION_RECEIPT_JSON_SCHEMA: Shape;
+export declare function parseFunnelOperationReceipt(value: unknown): FunnelOperationReceipt;
+export declare const FUNNEL_BRAND_SNAPSHOT_JSON_SCHEMA: Shape;
+export declare function parseFunnelBrandSnapshot(value: unknown): FunnelBrandSnapshot;
+export interface FunnelCatalogItem {
+    id: string;
+    label: string;
+}
+export interface FunnelFormChoice extends FunnelCatalogItem {
+    slug: string;
+    site: string | null;
+    formType: string;
+    active: boolean;
+    newsletterListIds: string[];
+    fields: {
+        slug: string;
+        type: string;
+        label: string;
+        required: boolean;
+    }[];
+}
+export interface FunnelListChoice extends FunnelCatalogItem {
+    active: boolean;
+    doubleOptIn: boolean;
+}
+export interface FunnelEmailTemplateChoice extends FunnelCatalogItem {
+    subject: string;
+    updatedAt: string | null;
+}
+export interface FunnelAssetChoice extends FunnelCatalogItem {
+    mimeType: string;
+    sizeBytes: number;
+    visibility: 'public';
+    publicUrl: string;
+    version: string | null;
+}
+export interface FunnelOwnerChoice extends FunnelCatalogItem {
+    active: true;
+}
+export interface FunnelBookingChoice extends FunnelCatalogItem {
+    site: string | null;
+    active: true;
+    requiresConfirmation: boolean;
+}
+export interface FunnelChoicePage<T> {
+    items: T[];
+    nextCursor: string | null;
+}
+export interface FunnelCatalog {
+    templates: {
+        id: FunnelTemplate;
+        label: string;
+        defaults: FunnelDraftDefinition;
+    }[];
+    sites: {
+        host: string;
+        label: string;
+    }[];
+    brand: FunnelBrandSnapshot | null;
+    choices: {
+        forms?: FunnelChoicePage<FunnelFormChoice>;
+        lists?: FunnelChoicePage<FunnelListChoice>;
+        emailTemplates?: FunnelChoicePage<FunnelEmailTemplateChoice>;
+        assets?: FunnelChoicePage<FunnelAssetChoice>;
+        owners?: FunnelChoicePage<FunnelOwnerChoice>;
+        bookingTypes?: FunnelChoicePage<FunnelBookingChoice>;
+    };
+    capabilities: {
+        managedPage: boolean;
+    };
+}
+export declare const FUNNEL_CATALOG_JSON_SCHEMA: Shape;
+export declare function parseFunnelCatalog(value: unknown): FunnelCatalog;
+export interface FunnelLaunchEvidence {
+    projectId: string;
+    orgId: string;
+    funnelId: string;
+    previewId: string;
+    versionId: string;
+    definitionRevision: number;
+    definitionDigest: string;
+    brandFingerprint: string;
+    resourceFingerprint: string;
+    entryDigest: string;
+    permissionDigest: string;
+    expiresAt: string;
+}
+export interface FunnelRollbackEvidence {
+    orgId: string;
+    projectId: string;
+    funnelId: string;
+    targetVersionId: string;
+    definitionRevision: number;
+    definitionDigest: string;
+    brandFingerprint: string;
+    resourceFingerprint: string;
+}
+export declare const FUNNEL_LAUNCH_EVIDENCE_JSON_SCHEMA: Shape;
+export declare function parseFunnelLaunchEvidence(value: unknown): FunnelLaunchEvidence;
+export declare const FUNNEL_ROLLBACK_EVIDENCE_JSON_SCHEMA: Shape;
+export declare function parseFunnelRollbackEvidence(value: unknown): FunnelRollbackEvidence;
+export declare const FUNNEL_PREVIEW_JSON_SCHEMA: Shape;
+export declare function parseFunnelPreview(value: unknown): FunnelPreview;
+export type FunnelEnrollmentState = 'waiting' | 'running' | 'completed' | 'exited' | 'needs_attention';
+export interface FunnelEnrollmentSummary {
+    id: string;
+    versionId: string;
+    state: FunnelEnrollmentState;
+    effectiveStatus: FunnelEnrollmentState | 'paused';
+    source: {
+        submissionId: string;
+        acceptedAt: string;
+    };
+    subject: {
+        kind: 'subscriber' | 'contact' | 'submission';
+        id: string;
+        displayLabel: string;
+    };
+    enteredAt: string;
+    nextRunAt: string | null;
+    exitCode: string | null;
+    stepsCompleted: number;
+    stepsTotal: number;
+    lastReceiptAt: string | null;
+}
+export interface FunnelTimeline {
+    items: {
+        executionId: string;
+        stepId: string;
+        type: FunnelStep['type'];
+        state: 'pending' | 'claimed' | 'queued' | 'admitted' | 'succeeded' | 'skipped' | 'uncertain' | 'failed';
+        dueAt: string | null;
+        occurredAt: string | null;
+        attempt: number;
+        reasonCode: string | null;
+        message: string;
+        receipt: {
+            domain: 'campaign_send' | 'subscriber_tag' | 'crm_task' | 'wait';
+            id: string | null;
+            state: string;
+        } | null;
+        canRetry: boolean;
+    }[];
+    nextCursor: string | null;
+    exit: {
+        code: string;
+        sourceType: string;
+        sourceId: string | null;
+        occurredAt: string;
+    } | null;
+}
+export declare const FUNNEL_SUMMARY_JSON_SCHEMA: Shape;
+export declare function parseFunnelSummary(value: unknown): FunnelSummary;
+export declare const FUNNEL_ENROLLMENT_JSON_SCHEMA: Shape;
+export declare function parseFunnelEnrollmentSummary(value: unknown): FunnelEnrollmentSummary;
+export declare const FUNNEL_TIMELINE_JSON_SCHEMA: Shape;
+export declare function parseFunnelTimeline(value: unknown): FunnelTimeline;
+export interface FunnelPublishedVersion {
+    versionId: string;
+    definitionRevision: number;
+    publishedAt: string;
+    brandFingerprint: string;
+    resourceFingerprint: string;
+    active: boolean;
+}
+export interface FunnelPublishedVersionDetail extends FunnelPublishedVersion {
+    rollbackEvidence: FunnelRollbackEvidence;
+}
+export declare const FUNNEL_VERSION_JSON_SCHEMA: Shape;
+export declare const FUNNEL_VERSION_DETAIL_JSON_SCHEMA: Shape;
+export declare function parseFunnelPublishedVersion(value: unknown): FunnelPublishedVersion;
+export declare function parseFunnelPublishedVersionDetail(value: unknown): FunnelPublishedVersionDetail;