@orion-studios/cms 0.5.6 → 0.5.8

package/dist/server/index.d.ts

@@ -52,8 +52,10 @@ type CmsRoutesOptions = {
     allowedOrigins?: string[];
     /** Rate limiter for public submissions. Defaults to in-memory (5/min/IP). */
     rateLimitStore?: RateLimitStore | null;
-    /** Token accepted by POST /sync and POST /cron/* in addition to admin bearer auth. */
+    /** Token accepted only by POST /sync in addition to admin bearer auth. */
     syncToken?: string;
+    /** Token accepted only by POST or GET /cron/publish-due. */
+    cronToken?: string;
     /** Extra domains never flagged as email typos. */
     knownGoodEmailDomains?: string[];
     /**
@@ -63,8 +65,20 @@ type CmsRoutesOptions = {
     sendEmail?: EmailSender | null;
     /** Site name used in notification emails. */
     siteName?: string;
-    /** Secret for draft preview tokens. Defaults to the service-role key. */
+    /** Purpose-specific secret for draft preview grants. */
     previewSecret?: string;
+    /** Stable identifier for the active preview signing key. */
+    previewKeyId?: string;
+    /** Optional prior preview key accepted only through the bounded overlap. */
+    previewPreviousSecret?: string;
+    previewPreviousKeyId?: string;
+    previewPreviousValidUntil?: number;
+    /** Stable Supabase project reference bound into preview grants. */
+    projectRef?: string;
+    /** Purpose-specific secret for analytics visitor and session hashing. */
+    analyticsSecret?: string;
+    /** Purpose-specific secret for auto-reply recipient hashing. */
+    autoReplyHashSecret?: string;
     /** Cloudflare Turnstile secret — when set, public submits must include a valid `_turnstileToken`. */
     turnstileSecret?: string;
     /** Max upload size in bytes (default 15 MB). */
@@ -120,10 +134,35 @@ declare function createCmsRoutes(options: CmsRoutesOptions): {
 };
 
 declare const PREVIEW_TOKEN_TTL_MS: number;
+declare const PREVIEW_TOKEN_MAX_USES = 8;
 declare const PREVIEW_SESSION_COOKIE = "orion_preview_session";
-declare function createPreviewToken(pageId: string, secret: string, ttlMs?: number): string;
-/** Returns the page id when the token is valid and unexpired, else null. */
-declare function verifyPreviewToken(token: string, secret: string): string | null;
+type PreviewSigningKey = {
+    id: string;
+    secret: string;
+};
+type PreviewKeyRing = {
+    active: PreviewSigningKey;
+    previous?: PreviewSigningKey & {
+        acceptUntil: number;
+    };
+};
+type PreviewGrantClaims = {
+    version: 1;
+    audience: 'cms-preview';
+    operation: 'read-draft';
+    keyId: string;
+    grantId: string;
+    pageId: string;
+    userId: string;
+    projectRef: string;
+    issuedAt: number;
+    expiresAt: number;
+};
+declare function createPreviewToken(grant: Omit<PreviewGrantClaims, 'version' | 'audience' | 'operation' | 'keyId' | 'issuedAt' | 'expiresAt'>, keys: PreviewKeyRing | string, ttlMs?: number): string;
+/** Returns bound claims when the token is valid and unexpired, else null. */
+declare function verifyPreviewGrantToken(token: string, keys: PreviewKeyRing | string, now?: number): PreviewGrantClaims | null;
+/** Compatibility helper for callers that only need the signed page binding. */
+declare function verifyPreviewToken(token: string, keys: PreviewKeyRing | string): string | null;
 type PreviewPage = {
     id: string;
     slug: string;
@@ -136,7 +175,7 @@ type PreviewPage = {
  * Site-side helper: verifies a preview token and loads the page's DRAFT
  * layout with the given (service or memory) client.
  */
-declare function getPreviewPage(client: SupabaseClient, token: string, secret: string): Promise<PreviewPage | null>;
+declare function getPreviewPage(client: SupabaseClient, token: string, keys: PreviewKeyRing | string, expectedProjectRef: string): Promise<PreviewPage | null>;
 
 /**
  * Pure analytics aggregation: raw event rows in, the full dashboard payload
@@ -144,8 +183,8 @@ declare function getPreviewPage(client: SupabaseClient, token: string, secret: s
  * and memory backends and is trivially testable.
  *
  * Call and email taps are useful interaction counts, but browser events are
- * forgeable. A conversion requires a server-verified event, currently a form
- * submission recorded after the authoritative lead write succeeds.
+ * forgeable. Form conversions come from authoritative submission rows. Any
+ * other conversion requires a server-verified event.
  */
 type StoredEvent = {
     id?: number | string;
@@ -163,6 +202,12 @@ type StoredEvent = {
     server_verified?: boolean;
     created_at: string;
 };
+/** Minimal authoritative form record used by aggregate analytics. */
+type StoredFormSubmission = {
+    form: string;
+    session_key: string;
+    created_at: string;
+};
 type AnalyticsKpis = {
     visitors: number;
     identifiedVisitors: number;
@@ -228,7 +273,7 @@ type AnalyticsSummary = {
 declare function aggregateAnalytics(events: StoredEvent[], previousEvents: StoredEvent[], range: {
     from: string;
     to: string;
-}): AnalyticsSummary;
+}, submissions?: StoredFormSubmission[], previousSubmissions?: StoredFormSubmission[]): AnalyticsSummary;
 
 /**
  * Server-side analytics ingest: validation, bot filtering, and the
@@ -301,9 +346,11 @@ declare function geoFrom(request: Request): {
  *   access token), verified via auth.getUser(). Stateless: no cookie plumbing.
  */
 type CmsEnv = {
+    expectedProjectRef: string;
     supabaseUrl: string;
     serviceRoleKey: string;
 };
+declare function validateCmsEnv(env: CmsEnv): CmsEnv;
 declare function readCmsEnv(): CmsEnv;
 declare function getServiceClient(env?: CmsEnv): SupabaseClient;
 /** Test seam: inject a fake client. */
@@ -333,14 +380,6 @@ declare function can(user: CmsUser | null, action: CmsAction): boolean;
  */
 declare function isStructuralChange(previous: PageLayout, next: PageLayout): boolean;
 
-/**
- * Content-as-code sync: the single implementation used by both the
- * POST /api/cms/sync route and local `npm run sync` scripts.
- *
- * Contract (proven on Currin): create missing pages, refresh metadata always,
- * write layouts only where the page is not builder-owned, upsert globals and
- * forms. Idempotent.
- */
 type SyncPageInput = {
     slug: string;
     path?: string;
@@ -358,6 +397,11 @@ type SyncFormInput = {
     config?: Record<string, unknown>;
     successMessage?: string;
 };
+type SyncRedirectInput = {
+    fromPath: string;
+    toPath: string;
+    permanent?: boolean;
+};
 type SyncMediaInput = {
     storagePath: string;
     filename?: string;
@@ -373,8 +417,27 @@ type SyncInput = {
     globals?: SyncGlobalInput[];
     forms?: SyncFormInput[];
     media?: SyncMediaInput[];
+    redirects?: SyncRedirectInput[];
+};
+type SyncOperation = {
+    kind: 'page' | 'global' | 'form' | 'media' | 'redirect';
+    key: string;
+    action: 'create' | 'update' | 'noop' | 'conflict' | 'blocked-delete';
+};
+type SyncPlan = {
+    mode: 'dry-run';
+    manifestHash: string;
+    targetReceiptHash: string;
+    operations: SyncOperation[];
+    skipped: Array<{
+        slug: string;
+        issues: unknown;
+    }>;
 };
 type SyncResult = {
+    mode: 'apply';
+    manifestHash: string;
+    targetReceiptHash: string;
     synced: string[];
     skipped: Array<{
         slug: string;
@@ -383,14 +446,23 @@ type SyncResult = {
     globals: number;
     forms: number;
     media: number;
-    /** Non-page resources that failed to write (globals/forms). */
     failed: Array<{
-        kind: 'global' | 'form';
+        kind: SyncOperation['kind'];
         key: string;
         error: string;
     }>;
+    conflicts: SyncOperation[];
+};
+type SyncOptions = {
+    mode?: 'dry-run';
+    expectedProjectRef?: string;
+} | {
+    mode: 'apply';
+    expectedManifestHash: string;
+    expectedProjectRef?: string;
+    expectedTargetReceiptHash: string;
 };
-declare function runContentSync(client: SupabaseClient, registry: BlockRegistry, input: SyncInput): Promise<SyncResult>;
+declare function runContentSync(client: SupabaseClient, registry: BlockRegistry, input: SyncInput, options?: SyncOptions): Promise<SyncPlan | SyncResult>;
 
 /**
  * In-memory CMS backend for local development and end-to-end tests.
@@ -423,4 +495,4 @@ declare function createMemoryCms(): MemoryCms;
 /** Process-wide singleton for Next.js dev servers (module state survives HMR via globalThis). */
 declare function getMemoryCms(): MemoryCms;
 
-export { type AnalyticsEventType, type AnalyticsKpis, type AnalyticsSummary, type CmsAction, type CmsEnv, type CmsRole, type CmsRoutesOptions, type CmsUser, type EmailMessage, type EmailSender, type IncomingEvent, MEMORY_DEV_TOKEN, type MemoryCms, PREVIEW_SESSION_COOKIE, PREVIEW_TOKEN_TTL_MS, type PreviewPage, type ResendSenderOptions, type StoredEvent, type SyncFormInput, type SyncGlobalInput, type SyncInput, type SyncMediaInput, type SyncPageInput, type SyncResult, aggregateAnalytics, can, createCmsRoutes, createDurableRateLimitStore, createMemoryCms, createPreviewToken, createResendSender, deviceFrom, formatSubmissionText, geoFrom, getMemoryCms, getPreviewPage, getServiceClient, isBotRequest, isStructuralChange, notifySubmission, parseEventBatch, readCmsEnv, resolveUser, runContentSync, sessionKeyFor, setServiceClientForTesting, verifyPreviewToken, visitorKeyFor };
+export { type AnalyticsEventType, type AnalyticsKpis, type AnalyticsSummary, type CmsAction, type CmsEnv, type CmsRole, type CmsRoutesOptions, type CmsUser, type EmailMessage, type EmailSender, type IncomingEvent, MEMORY_DEV_TOKEN, type MemoryCms, PREVIEW_SESSION_COOKIE, PREVIEW_TOKEN_MAX_USES, PREVIEW_TOKEN_TTL_MS, type PreviewGrantClaims, type PreviewPage, type ResendSenderOptions, type StoredEvent, type StoredFormSubmission, type SyncFormInput, type SyncGlobalInput, type SyncInput, type SyncMediaInput, type SyncOperation, type SyncOptions, type SyncPageInput, type SyncPlan, type SyncResult, aggregateAnalytics, can, createCmsRoutes, createDurableRateLimitStore, createMemoryCms, createPreviewToken, createResendSender, deviceFrom, formatSubmissionText, geoFrom, getMemoryCms, getPreviewPage, getServiceClient, isBotRequest, isStructuralChange, notifySubmission, parseEventBatch, readCmsEnv, resolveUser, runContentSync, sessionKeyFor, setServiceClientForTesting, validateCmsEnv, verifyPreviewGrantToken, verifyPreviewToken, visitorKeyFor };