@neuraloom/contracts 0.0.0-stage → 0.1.22

package/dist/marketing/marketing-visibility-overview.schema.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MarketingRecommendationsGenerateResponseSchema = exports.MarketingVisibilityOverviewResponseSchema = exports.MarketingVisibilityOverviewSchema = void 0;
+const zod_1 = require("zod");
+const date_range_schema_1 = require("./date-range.schema");
+const marketing_challenge_performance_schema_1 = require("./marketing-challenge-performance.schema");
+const marketing_landing_page_intelligence_schema_1 = require("./marketing-landing-page-intelligence.schema");
+const marketing_executive_overview_schema_1 = require("./marketing-executive-overview.schema");
+const acquisition_recommendation_schema_1 = require("./acquisition-recommendation.schema");
+const marketing_world_performance_schema_1 = require("./marketing-world-performance.schema");
+exports.MarketingVisibilityOverviewSchema = zod_1.z
+    .object({
+    dateRange: date_range_schema_1.MarketingDateRangeSchema,
+    warehouse: marketing_executive_overview_schema_1.MarketingWarehouseSummarySchema,
+    worlds: zod_1.z.array(marketing_world_performance_schema_1.MarketingWorldPerformanceSchema),
+    challenges: zod_1.z.array(marketing_challenge_performance_schema_1.MarketingChallengePerformanceSchema),
+    landingPages: zod_1.z.array(marketing_landing_page_intelligence_schema_1.MarketingLandingPageIntelligenceSchema),
+})
+    .strict();
+exports.MarketingVisibilityOverviewResponseSchema = zod_1.z
+    .object({
+    success: zod_1.z.literal(true),
+    data: exports.MarketingVisibilityOverviewSchema,
+})
+    .strict();
+exports.MarketingRecommendationsGenerateResponseSchema = zod_1.z
+    .object({
+    success: zod_1.z.literal(true),
+    data: zod_1.z
+        .object({
+        generatedAt: zod_1.z.string().datetime(),
+        recommendations: zod_1.z.array(acquisition_recommendation_schema_1.AcquisitionRecommendationSchema),
+        meta: zod_1.z
+            .object({
+            rulesVersion: zod_1.z.string(),
+            keywordOpportunityCount: zod_1.z.number().int().nonnegative(),
+        })
+            .strict(),
+    })
+        .strict(),
+})
+    .strict();

package/dist/marketing/marketing-world-catalog.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Canonical world/challenge slugs for marketing performance rollups (operator dashboards).
+ * @see .cursor/plans/community-movie/marketing-intelligence/09-world-challenge-performance.md
+ */
+export type MarketingWorldCatalogEntry = {
+    readonly slug: string;
+    readonly title: string;
+    readonly challengeSlug: string | null;
+};
+export declare const MARKETING_WORLD_CATALOG: readonly MarketingWorldCatalogEntry[];

package/dist/marketing/marketing-world-catalog.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * Canonical world/challenge slugs for marketing performance rollups (operator dashboards).
+ * @see .cursor/plans/community-movie/marketing-intelligence/09-world-challenge-performance.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MARKETING_WORLD_CATALOG = void 0;
+exports.MARKETING_WORLD_CATALOG = [
+    { slug: 'aokujima', title: 'Aokujima', challengeSlug: 'aokujima' },
+    { slug: 'neon-tide', title: 'Neon Tide', challengeSlug: 'neon-tide' },
+    { slug: 'kagami-1', title: 'KAGAMI-1', challengeSlug: null },
+    { slug: 'gearhaven', title: 'Gearhaven', challengeSlug: 'gearhaven' },
+    { slug: 'aves-de-venecia', title: 'Aves de Venecia', challengeSlug: 'aves-de-venecia' },
+    { slug: 'mars-last-garden', title: 'Mars: Last Garden', challengeSlug: 'mars-last-garden' },
+    { slug: 'madame-pickwick', title: 'Picklewick Manor', challengeSlug: 'madame-pickwick' },
+];

package/dist/marketing/marketing-world-performance.schema.d.ts

@@ -0,0 +1,179 @@
+import { z } from 'zod';
+export declare const MarketingWorldPerformanceSchema: z.ZodObject<{
+    worldSlug: z.ZodString;
+    title: z.ZodString;
+    challengeSlug: z.ZodNullable<z.ZodString>;
+    viewWorldCount: z.ZodNumber;
+    viewChallengeCount: z.ZodNumber;
+    joinChallengeCount: z.ZodNumber;
+    submitIdeaCount: z.ZodNumber;
+    ga4Sessions: z.ZodNumber;
+    ga4Conversions: z.ZodNumber;
+    organicClicks: z.ZodNumber;
+    organicImpressions: z.ZodNumber;
+    qualifiedCreatorRate: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    title: string;
+    challengeSlug: string | null;
+    worldSlug: string;
+    viewWorldCount: number;
+    viewChallengeCount: number;
+    joinChallengeCount: number;
+    submitIdeaCount: number;
+    ga4Sessions: number;
+    ga4Conversions: number;
+    organicClicks: number;
+    organicImpressions: number;
+    qualifiedCreatorRate: number;
+}, {
+    title: string;
+    challengeSlug: string | null;
+    worldSlug: string;
+    viewWorldCount: number;
+    viewChallengeCount: number;
+    joinChallengeCount: number;
+    submitIdeaCount: number;
+    ga4Sessions: number;
+    ga4Conversions: number;
+    organicClicks: number;
+    organicImpressions: number;
+    qualifiedCreatorRate: number;
+}>;
+export type MarketingWorldPerformance = z.infer<typeof MarketingWorldPerformanceSchema>;
+export declare const MarketingWorldPerformanceListResponseSchema: z.ZodObject<{
+    success: z.ZodLiteral<true>;
+    data: z.ZodObject<{
+        dateRange: z.ZodObject<{
+            from: z.ZodString;
+            to: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            from: string;
+            to: string;
+        }, {
+            from: string;
+            to: string;
+        }>;
+        worlds: z.ZodArray<z.ZodObject<{
+            worldSlug: z.ZodString;
+            title: z.ZodString;
+            challengeSlug: z.ZodNullable<z.ZodString>;
+            viewWorldCount: z.ZodNumber;
+            viewChallengeCount: z.ZodNumber;
+            joinChallengeCount: z.ZodNumber;
+            submitIdeaCount: z.ZodNumber;
+            ga4Sessions: z.ZodNumber;
+            ga4Conversions: z.ZodNumber;
+            organicClicks: z.ZodNumber;
+            organicImpressions: z.ZodNumber;
+            qualifiedCreatorRate: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            title: string;
+            challengeSlug: string | null;
+            worldSlug: string;
+            viewWorldCount: number;
+            viewChallengeCount: number;
+            joinChallengeCount: number;
+            submitIdeaCount: number;
+            ga4Sessions: number;
+            ga4Conversions: number;
+            organicClicks: number;
+            organicImpressions: number;
+            qualifiedCreatorRate: number;
+        }, {
+            title: string;
+            challengeSlug: string | null;
+            worldSlug: string;
+            viewWorldCount: number;
+            viewChallengeCount: number;
+            joinChallengeCount: number;
+            submitIdeaCount: number;
+            ga4Sessions: number;
+            ga4Conversions: number;
+            organicClicks: number;
+            organicImpressions: number;
+            qualifiedCreatorRate: number;
+        }>, "many">;
+    }, "strict", z.ZodTypeAny, {
+        dateRange: {
+            from: string;
+            to: string;
+        };
+        worlds: {
+            title: string;
+            challengeSlug: string | null;
+            worldSlug: string;
+            viewWorldCount: number;
+            viewChallengeCount: number;
+            joinChallengeCount: number;
+            submitIdeaCount: number;
+            ga4Sessions: number;
+            ga4Conversions: number;
+            organicClicks: number;
+            organicImpressions: number;
+            qualifiedCreatorRate: number;
+        }[];
+    }, {
+        dateRange: {
+            from: string;
+            to: string;
+        };
+        worlds: {
+            title: string;
+            challengeSlug: string | null;
+            worldSlug: string;
+            viewWorldCount: number;
+            viewChallengeCount: number;
+            joinChallengeCount: number;
+            submitIdeaCount: number;
+            ga4Sessions: number;
+            ga4Conversions: number;
+            organicClicks: number;
+            organicImpressions: number;
+            qualifiedCreatorRate: number;
+        }[];
+    }>;
+}, "strict", z.ZodTypeAny, {
+    success: true;
+    data: {
+        dateRange: {
+            from: string;
+            to: string;
+        };
+        worlds: {
+            title: string;
+            challengeSlug: string | null;
+            worldSlug: string;
+            viewWorldCount: number;
+            viewChallengeCount: number;
+            joinChallengeCount: number;
+            submitIdeaCount: number;
+            ga4Sessions: number;
+            ga4Conversions: number;
+            organicClicks: number;
+            organicImpressions: number;
+            qualifiedCreatorRate: number;
+        }[];
+    };
+}, {
+    success: true;
+    data: {
+        dateRange: {
+            from: string;
+            to: string;
+        };
+        worlds: {
+            title: string;
+            challengeSlug: string | null;
+            worldSlug: string;
+            viewWorldCount: number;
+            viewChallengeCount: number;
+            joinChallengeCount: number;
+            submitIdeaCount: number;
+            ga4Sessions: number;
+            ga4Conversions: number;
+            organicClicks: number;
+            organicImpressions: number;
+            qualifiedCreatorRate: number;
+        }[];
+    };
+}>;

package/dist/marketing/marketing-world-performance.schema.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MarketingWorldPerformanceListResponseSchema = exports.MarketingWorldPerformanceSchema = void 0;
+const zod_1 = require("zod");
+const date_range_schema_1 = require("./date-range.schema");
+exports.MarketingWorldPerformanceSchema = zod_1.z
+    .object({
+    worldSlug: zod_1.z.string().min(1).max(128),
+    title: zod_1.z.string().min(1).max(256),
+    challengeSlug: zod_1.z.string().min(1).max(128).nullable(),
+    viewWorldCount: zod_1.z.number().int().nonnegative(),
+    viewChallengeCount: zod_1.z.number().int().nonnegative(),
+    joinChallengeCount: zod_1.z.number().int().nonnegative(),
+    submitIdeaCount: zod_1.z.number().int().nonnegative(),
+    ga4Sessions: zod_1.z.number().int().nonnegative(),
+    ga4Conversions: zod_1.z.number().int().nonnegative(),
+    organicClicks: zod_1.z.number().int().nonnegative(),
+    organicImpressions: zod_1.z.number().int().nonnegative(),
+    qualifiedCreatorRate: zod_1.z.number().min(0).max(1),
+})
+    .strict();
+exports.MarketingWorldPerformanceListResponseSchema = zod_1.z
+    .object({
+    success: zod_1.z.literal(true),
+    data: zod_1.z
+        .object({
+        dateRange: date_range_schema_1.MarketingDateRangeSchema,
+        worlds: zod_1.z.array(exports.MarketingWorldPerformanceSchema),
+    })
+        .strict(),
+})
+    .strict();

package/dist/marketing/routes.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Marketing Intelligence API routes — SSOT for operator dashboards and internal agents.
+ * @see .cursor/plans/community-movie/marketing-intelligence/19-dashboard-roadmap.md
+ */
+export declare const MARKETING_ROUTES: {
+    readonly health: "/api/internal/marketing/health";
+    readonly readiness: "/api/internal/marketing/readiness";
+    readonly executive: "/api/internal/marketing/executive";
+    readonly overview: "/api/internal/marketing/overview";
+    readonly conversions: {
+        readonly enqueue: "/api/internal/marketing/conversions/enqueue";
+        readonly flush: "/api/internal/marketing/conversions/flush";
+    };
+    readonly ads: {
+        readonly root: "/api/internal/marketing/ads";
+        readonly accounts: "/api/internal/marketing/ads/accounts";
+        readonly campaigns: "/api/internal/marketing/ads/campaigns";
+        readonly adGroups: "/api/internal/marketing/ads/ad-groups";
+        readonly keywords: "/api/internal/marketing/ads/keywords";
+        readonly searchTerms: "/api/internal/marketing/ads/search-terms";
+        readonly metrics: "/api/internal/marketing/ads/metrics";
+        readonly conversions: "/api/internal/marketing/ads/conversions";
+        readonly overview: "/api/internal/marketing/ads/overview";
+    };
+    readonly ga4: {
+        readonly overview: "/api/internal/marketing/ga4/overview";
+        readonly traffic: "/api/internal/marketing/ga4/traffic";
+        readonly landingPages: "/api/internal/marketing/ga4/landing-pages";
+        readonly events: "/api/internal/marketing/ga4/events";
+        readonly funnel: "/api/internal/marketing/ga4/funnel";
+    };
+    readonly organic: "/api/internal/marketing/organic";
+    readonly landingPages: {
+        readonly list: "/api/internal/marketing/landing-pages";
+        readonly detail: (path: string) => string;
+        readonly scorecard: (path: string) => string;
+    };
+    readonly worlds: {
+        readonly list: "/api/internal/marketing/worlds";
+        readonly detail: (worldSlug: string) => string;
+        readonly retention: "/api/internal/marketing/worlds/retention";
+        readonly affinityClusters: "/api/internal/marketing/worlds/affinity-clusters";
+    };
+    readonly challenges: {
+        readonly list: "/api/internal/marketing/challenges";
+        readonly detail: (challengeSlug: string) => string;
+    };
+    readonly keywords: {
+        readonly opportunities: "/api/internal/marketing/keywords/opportunities";
+    };
+    readonly funnel: "/api/internal/marketing/funnel";
+    readonly attribution: "/api/internal/marketing/attribution";
+    readonly campaigns: {
+        readonly drafts: "/api/internal/marketing/campaigns/drafts";
+        readonly draftDetail: (id: string) => string;
+        readonly approveDraft: (id: string) => string;
+        readonly publishDraft: (id: string) => string;
+        readonly rejectDraft: (id: string) => string;
+    };
+    readonly creative: {
+        readonly recommendations: "/api/internal/marketing/creative/recommendations";
+    };
+    readonly audiences: "/api/internal/marketing/audiences";
+    readonly agents: {
+        readonly audit: "/api/internal/marketing/agents/audit";
+    };
+    readonly recommendations: {
+        readonly list: "/api/internal/marketing/recommendations";
+        readonly detail: (id: string) => string;
+        readonly generate: "/api/internal/marketing/recommendations/generate";
+        readonly approve: (id: string) => string;
+        readonly reject: (id: string) => string;
+        readonly apply: (id: string) => string;
+    };
+};
+export type MarketingAdsRouteKey = keyof typeof MARKETING_ROUTES.ads;
+export type MarketingGa4RouteKey = keyof typeof MARKETING_ROUTES.ga4;

package/dist/marketing/routes.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Marketing Intelligence API routes — SSOT for operator dashboards and internal agents.
+ * @see .cursor/plans/community-movie/marketing-intelligence/19-dashboard-roadmap.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MARKETING_ROUTES = void 0;
+const P = '/api/internal/marketing';
+exports.MARKETING_ROUTES = {
+    health: `${P}/health`,
+    readiness: `${P}/readiness`,
+    executive: `${P}/executive`,
+    overview: `${P}/overview`,
+    conversions: {
+        enqueue: `${P}/conversions/enqueue`,
+        flush: `${P}/conversions/flush`,
+    },
+    ads: {
+        root: `${P}/ads`,
+        accounts: `${P}/ads/accounts`,
+        campaigns: `${P}/ads/campaigns`,
+        adGroups: `${P}/ads/ad-groups`,
+        keywords: `${P}/ads/keywords`,
+        searchTerms: `${P}/ads/search-terms`,
+        metrics: `${P}/ads/metrics`,
+        conversions: `${P}/ads/conversions`,
+        overview: `${P}/ads/overview`,
+    },
+    ga4: {
+        overview: `${P}/ga4/overview`,
+        traffic: `${P}/ga4/traffic`,
+        landingPages: `${P}/ga4/landing-pages`,
+        events: `${P}/ga4/events`,
+        funnel: `${P}/ga4/funnel`,
+    },
+    organic: `${P}/organic`,
+    landingPages: {
+        list: `${P}/landing-pages`,
+        detail: (path) => `${P}/landing-pages/${encodeURIComponent(path)}`,
+        scorecard: (path) => `${P}/landing-pages/${encodeURIComponent(path)}/scorecard`,
+    },
+    worlds: {
+        list: `${P}/worlds`,
+        detail: (worldSlug) => `${P}/worlds/${encodeURIComponent(worldSlug)}`,
+        retention: `${P}/worlds/retention`,
+        affinityClusters: `${P}/worlds/affinity-clusters`,
+    },
+    challenges: {
+        list: `${P}/challenges`,
+        detail: (challengeSlug) => `${P}/challenges/${encodeURIComponent(challengeSlug)}`,
+    },
+    keywords: {
+        opportunities: `${P}/keywords/opportunities`,
+    },
+    funnel: `${P}/funnel`,
+    attribution: `${P}/attribution`,
+    campaigns: {
+        drafts: `${P}/campaigns/drafts`,
+        draftDetail: (id) => `${P}/campaigns/drafts/${encodeURIComponent(id)}`,
+        approveDraft: (id) => `${P}/campaigns/drafts/${encodeURIComponent(id)}/approve`,
+        publishDraft: (id) => `${P}/campaigns/drafts/${encodeURIComponent(id)}/publish`,
+        rejectDraft: (id) => `${P}/campaigns/drafts/${encodeURIComponent(id)}/reject`,
+    },
+    creative: {
+        recommendations: `${P}/creative/recommendations`,
+    },
+    audiences: `${P}/audiences`,
+    agents: {
+        audit: `${P}/agents/audit`,
+    },
+    recommendations: {
+        list: `${P}/recommendations`,
+        detail: (id) => `${P}/recommendations/${encodeURIComponent(id)}`,
+        generate: `${P}/recommendations/generate`,
+        approve: (id) => `${P}/recommendations/${encodeURIComponent(id)}/approve`,
+        reject: (id) => `${P}/recommendations/${encodeURIComponent(id)}/reject`,
+        apply: (id) => `${P}/recommendations/${encodeURIComponent(id)}/apply`,
+    },
+};

package/dist/marketing/search-negative-keywords.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Shared negative keyword list for CM | World Discovery Search campaigns.
+ * Applied at campaign level in setup-community-movie-search-campaign.mjs.
+ */
+export declare const COMMUNITY_MOVIE_SEARCH_NEGATIVE_KEYWORDS: readonly ["free movies", "movie downloads", "torrent", "netflix", "piracy", "pirate", "watch free", "123movies", "putlocker", "ai girlfriend", "ai boyfriend", "meme generator", "stock footage", "stock video", "video editor free", "capcut", "deepfake", "celebrity deepfake", "jobs", "casting call los angeles", "film school application"];
+export type CommunityMovieSearchNegativeKeyword = (typeof COMMUNITY_MOVIE_SEARCH_NEGATIVE_KEYWORDS)[number];

package/dist/marketing/search-negative-keywords.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMUNITY_MOVIE_SEARCH_NEGATIVE_KEYWORDS = void 0;
+/**
+ * Shared negative keyword list for CM | World Discovery Search campaigns.
+ * Applied at campaign level in setup-community-movie-search-campaign.mjs.
+ */
+exports.COMMUNITY_MOVIE_SEARCH_NEGATIVE_KEYWORDS = [
+    'free movies',
+    'movie downloads',
+    'torrent',
+    'netflix',
+    'piracy',
+    'pirate',
+    'watch free',
+    '123movies',
+    'putlocker',
+    'ai girlfriend',
+    'ai boyfriend',
+    'meme generator',
+    'stock footage',
+    'stock video',
+    'video editor free',
+    'capcut',
+    'deepfake',
+    'celebrity deepfake',
+    'jobs',
+    'casting call los angeles',
+    'film school application',
+];

package/dist/registry/schema-registry.d.ts

@@ -0,0 +1,74 @@
+/**
+ * NeuraLoom Canonical Schema Registry
+ *
+ * This is the single source of truth for all workflow payload schemas,
+ * artifact schemas, and data contracts across every workflow channel.
+ *
+ * Constitutional Law §3 (Schema Law):
+ * Every persisted workflow artifact must reference a registered schemaKey
+ * and schemaVersion. Artifacts with unregistered schemas cannot satisfy completion.
+ *
+ * Registry Law: If it is not registered, it is not canonical.
+ */
+export type SchemaDomain = 'workflow' | 'software' | 'writing' | 'fiction' | 'research' | 'media' | 'publication' | 'transformation' | 'guardian' | 'knowledge_graph' | 'integrations' | 'telemetry';
+export type SchemaStatus = 'canonical_active' | 'canonical_planned' | 'legacy_compat' | 'deprecated' | 'experimental';
+export type SchemaRegistryEntry = {
+    schemaKey: string;
+    schemaVersion: string;
+    domain: SchemaDomain;
+    workflowVariant?: string;
+    stepId?: string;
+    stageId?: string;
+    artifactType?: string;
+    /** Name of the exported Zod schema from @neuraloom/contracts */
+    zodSchemaExport: string;
+    /** Name of the exported JSON schema, if available */
+    jsonSchemaExport?: string;
+    /** Name of the exported TypeScript type, if available */
+    typescriptTypeExport?: string;
+    producedBy?: {
+        orchestratorKey?: string;
+        routeKey?: string;
+        workflowStep?: string;
+    };
+    consumedBy?: Array<{
+        workflowVariant?: string;
+        stepId?: string;
+        routeKey?: string;
+        componentKey?: string;
+        orchestratorKey?: string;
+    }>;
+    /** Database tables that persist this schema's artifacts */
+    dbTables?: string[];
+    status: SchemaStatus;
+    /** If deprecated, the replacement schemaKey */
+    replacementSchemaKey?: string;
+    notes?: string;
+};
+declare const SCHEMA_REGISTRY_ENTRIES: readonly SchemaRegistryEntry[];
+/** Return a registry entry by its canonical schemaKey. */
+export declare function getSchemaEntry(schemaKey: string): SchemaRegistryEntry | undefined;
+/** Return all entries for a given workflow variant. */
+export declare function getSchemasForWorkflowVariant(workflowVariant: string): SchemaRegistryEntry[];
+/** Return all entries for a given workflow step within a variant. */
+export declare function getSchemasForStep(workflowVariant: string, stepId: string): SchemaRegistryEntry[];
+/** Return the registry entry for a given artifact type key. */
+export declare function getSchemaForArtifactType(artifactType: string): SchemaRegistryEntry | undefined;
+/**
+ * Assert that a schemaKey is registered.
+ * Throws if the key is not found — use in Guardian/compile-time checks.
+ */
+export declare function assertSchemaRegistered(schemaKey: string): void;
+/**
+ * Assert that an artifactType has a registered schema.
+ * Throws if not found — use in workflow completion gates.
+ */
+export declare function assertArtifactSchemaRegistered(artifactType: string): void;
+/** Return all entries for a specific domain. */
+export declare function getSchemasForDomain(domain: SchemaDomain): SchemaRegistryEntry[];
+/** Return all canonical_active entries. */
+export declare function getActiveSchemas(): SchemaRegistryEntry[];
+/** Return all deprecated entries that have no replacement. */
+export declare function getDeprecatedWithoutReplacement(): SchemaRegistryEntry[];
+export { SCHEMA_REGISTRY_ENTRIES };
+export type { SchemaRegistryEntry as SchemaRegistryEntryType };