@endora-commerce/contracts 0.100.0

package/dist/megamenu.js

@@ -0,0 +1,186 @@
+// Megamenu — feature 015 contract surface.
+// Pages, Bindings, Items (with a discriminated-union target shape), the
+// resolved storefront payload. Per Principle V these schemas are the
+// source of truth for every HTTP boundary in the new `megamenu` module.
+import { z } from 'zod';
+import { isoDateTimeSchema, multilingualStringSchema, uuidSchema } from './common.js';
+// ────────────────────────────────────────────────────────────────────
+// Domain primitives
+// ────────────────────────────────────────────────────────────────────
+export const megamenuItemKindSchema = z.enum([
+    'category-link',
+    'cms-page-link',
+    'external-link',
+    'button',
+    'asset',
+    'cms-block-embed',
+]);
+export const megamenuButtonVariantSchema = z.enum(['primary', 'secondary', 'ghost']);
+export const megamenuIconPositionSchema = z.enum(['left', 'right']);
+export const megamenuEmbedSideSchema = z.enum(['left', 'right']);
+export const megamenuAssetKindSchema = z.enum(['image', 'video']);
+const externalUrlRegex = /^(?:https?:\/\/|tel:|mailto:)/i;
+const externalUrlSchema = z
+    .string()
+    .min(1)
+    .max(2048)
+    .refine((value) => externalUrlRegex.test(value), {
+    message: 'External link must use http://, https://, tel:, or mailto: scheme.',
+});
+const buttonUrlSchema = z.string().min(1).max(2048);
+const optionalIconShape = {
+    iconAssetId: uuidSchema.nullable().optional(),
+    iconPosition: megamenuIconPositionSchema.nullable().optional(),
+};
+// ────────────────────────────────────────────────────────────────────
+// Item-level discriminated union — the wire shape carries `kind` at
+// the item level and the kind-specific fields collapsed into `target`.
+// ────────────────────────────────────────────────────────────────────
+export const megamenuItemBaseFields = {
+    id: uuidSchema.optional(),
+    parentId: uuidSchema.nullable().optional(),
+    position: z.number().int().nonnegative(),
+    labels: multilingualStringSchema,
+    descriptions: multilingualStringSchema.nullable().optional(),
+};
+export const categoryLinkTargetSchema = z.object({
+    categoryId: uuidSchema,
+    ...optionalIconShape,
+});
+export const cmsPageLinkTargetSchema = z.object({
+    pageId: uuidSchema,
+    ...optionalIconShape,
+});
+export const externalLinkTargetSchema = z.object({
+    url: externalUrlSchema,
+    ...optionalIconShape,
+});
+export const buttonTargetSchema = z.object({
+    url: buttonUrlSchema,
+    variant: megamenuButtonVariantSchema,
+});
+export const assetTargetSchema = z.union([
+    z.object({
+        assetId: uuidSchema,
+        kind: megamenuAssetKindSchema,
+    }),
+    z.object({
+        /** Free URL — replaced with assetId at save time via Assets Library import. */
+        url: z.string().url(),
+        kind: megamenuAssetKindSchema,
+    }),
+]);
+export const cmsBlockEmbedTargetSchema = z.object({
+    blockId: uuidSchema,
+    embedSide: megamenuEmbedSideSchema,
+});
+export const megamenuItemSchema = z.discriminatedUnion('kind', [
+    z.object({ ...megamenuItemBaseFields, kind: z.literal('category-link'), target: categoryLinkTargetSchema }),
+    z.object({ ...megamenuItemBaseFields, kind: z.literal('cms-page-link'), target: cmsPageLinkTargetSchema }),
+    z.object({ ...megamenuItemBaseFields, kind: z.literal('external-link'), target: externalLinkTargetSchema }),
+    z.object({ ...megamenuItemBaseFields, kind: z.literal('button'), target: buttonTargetSchema }),
+    z.object({ ...megamenuItemBaseFields, kind: z.literal('asset'), target: assetTargetSchema }),
+    z.object({ ...megamenuItemBaseFields, kind: z.literal('cms-block-embed'), target: cmsBlockEmbedTargetSchema }),
+]);
+// ────────────────────────────────────────────────────────────────────
+// Megamenu (configuration row)
+// ────────────────────────────────────────────────────────────────────
+export const megamenuBindingSchema = z.object({
+    salesChannelId: uuidSchema,
+    language: z.string().min(2).max(8),
+    active: z.boolean(),
+    version: z.number().int(),
+    createdAt: isoDateTimeSchema,
+    updatedAt: isoDateTimeSchema,
+});
+export const megamenuSummarySchema = z.object({
+    id: uuidSchema,
+    name: z.string(),
+    description: z.string().nullable(),
+    version: z.number().int(),
+    bindings: z.array(megamenuBindingSchema),
+    activeIn: z.number().int().nonnegative(),
+    createdAt: isoDateTimeSchema,
+    updatedAt: isoDateTimeSchema,
+});
+export const megamenuDetailSchema = megamenuSummarySchema.extend({
+    items: z.array(megamenuItemSchema),
+});
+export const createMegamenuRequestSchema = z.object({
+    name: z.string().min(1).max(200),
+    description: z.string().max(2000).nullable().optional(),
+});
+export const patchMegamenuRequestSchema = z
+    .object({
+    name: z.string().min(1).max(200).optional(),
+    description: z.string().max(2000).nullable().optional(),
+    version: z.number().int().optional(),
+})
+    .refine((x) => Object.keys(x).length > 0, { message: 'At least one field required.' });
+export const putItemsRequestSchema = z.object({
+    items: z.array(megamenuItemSchema),
+    version: z.number().int(),
+});
+export const addBindingRequestSchema = z.object({
+    salesChannelId: uuidSchema,
+    language: z.string().min(2).max(8),
+});
+export const activateBindingRequestSchema = addBindingRequestSchema;
+// ────────────────────────────────────────────────────────────────────
+// Storefront resolved payload (recursive)
+// ────────────────────────────────────────────────────────────────────
+export const megamenuResolvedIconSchema = z.object({
+    assetId: uuidSchema,
+    url: z.string(),
+    position: megamenuIconPositionSchema,
+});
+export const megamenuResolvedAssetSchema = z.object({
+    id: uuidSchema,
+    kind: megamenuAssetKindSchema,
+    url: z.string(),
+    label: z.string().nullable(),
+});
+export const megamenuResolvedBlockSchema = z.object({
+    id: uuidSchema,
+    code: z.string(),
+    language: z.string(),
+    content: z.object({ schemaVersion: z.number().int(), data: z.unknown() }),
+});
+const resolvedMenuItemBase = z.object({
+    id: uuidSchema,
+    parentId: uuidSchema.nullable(),
+    kind: megamenuItemKindSchema,
+    label: z.string(),
+    description: z.string().nullable().optional(),
+    url: z.string().optional(),
+    icon: megamenuResolvedIconSchema.nullable().optional(),
+    variant: megamenuButtonVariantSchema.optional(),
+    asset: megamenuResolvedAssetSchema.optional(),
+    block: megamenuResolvedBlockSchema.optional(),
+    embedSide: megamenuEmbedSideSchema.optional(),
+});
+export const resolvedMenuItemSchema = z.lazy(() => resolvedMenuItemBase.extend({ children: z.array(resolvedMenuItemSchema) }));
+export const resolvedMegamenuSchema = z.object({
+    megamenuId: uuidSchema,
+    name: z.string(),
+    language: z.string(),
+    items: z.array(resolvedMenuItemSchema),
+});
+// ────────────────────────────────────────────────────────────────────
+// Activate response — surfaces the previously-active menu so the admin
+// can render a "switched from <name>" confirmation.
+// ────────────────────────────────────────────────────────────────────
+export const activateBindingResponseSchema = z.object({
+    activated: z.object({
+        megamenuId: uuidSchema,
+        salesChannelId: uuidSchema,
+        language: z.string(),
+    }),
+    previouslyActive: z
+        .object({
+        megamenuId: uuidSchema,
+        name: z.string(),
+    })
+        .nullable(),
+});
+//# sourceMappingURL=megamenu.js.map

package/dist/megamenu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"megamenu.js","sourceRoot":"","sources":["../src/megamenu.ts"],"names":[],"mappings":"AAAA,2CAA2C;AAC3C,wEAAwE;AACxE,qEAAqE;AACrE,wEAAwE;AAExE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEtF,uEAAuE;AACvE,oBAAoB;AACpB,uEAAuE;AAEvE,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,IAAI,CAAC;IAC3C,eAAe;IACf,eAAe;IACf,eAAe;IACf,QAAQ;IACR,OAAO;IACP,iBAAiB;CAClB,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,CAAC;AAGrF,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAGpE,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;AAGjE,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;AAGlE,MAAM,gBAAgB,GAAG,gCAAgC,CAAC;AAC1D,MAAM,iBAAiB,GAAG,CAAC;KACxB,MAAM,EAAE;KACR,GAAG,CAAC,CAAC,CAAC;KACN,GAAG,CAAC,IAAI,CAAC;KACT,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,gBAAgB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE;IAC/C,OAAO,EAAE,oEAAoE;CAC9E,CAAC,CAAC;AAEL,MAAM,eAAe,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAEpD,MAAM,iBAAiB,GAAG;IACxB,WAAW,EAAE,UAAU,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC7C,YAAY,EAAE,0BAA0B,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CAC/D,CAAC;AAEF,uEAAuE;AACvE,oEAAoE;AACpE,uEAAuE;AACvE,uEAAuE;AAEvE,MAAM,CAAC,MAAM,sBAAsB,GAAG;IACpC,EAAE,EAAE,UAAU,CAAC,QAAQ,EAAE;IACzB,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC1C,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACxC,MAAM,EAAE,wBAAwB;IAChC,YAAY,EAAE,wBAAwB,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CACpD,CAAC;AAEX,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,UAAU,EAAE,UAAU;IACtB,GAAG,iBAAiB;CACrB,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,MAAM,EAAE,UAAU;IAClB,GAAG,iBAAiB;CACrB,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC/C,GAAG,EAAE,iBAAiB;IACtB,GAAG,iBAAiB;CACrB,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IACzC,GAAG,EAAE,eAAe;IACpB,OAAO,EAAE,2BAA2B;CACrC,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC;IACvC,CAAC,CAAC,MAAM,CAAC;QACP,OAAO,EAAE,UAAU;QACnB,IAAI,EAAE,uBAAuB;KAC9B,CAAC;IACF,CAAC,CAAC,MAAM,CAAC;QACP,+EAA+E;QAC/E,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;QACrB,IAAI,EAAE,uBAAuB;KAC9B,CAAC;CACH,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD,OAAO,EAAE,UAAU;IACnB,SAAS,EAAE,uBAAuB;CACnC,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IAC7D,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,sBAAsB,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;IAC3G,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,sBAAsB,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,MAAM,EAAE,uBAAuB,EAAE,CAAC;IAC1G,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,sBAAsB,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;IAC3G,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,sBAAsB,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC;IAC9F,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,sBAAsB,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5F,CAAC,CAAC,MAAM,CAAC,EAAE,GAAG,sBAAsB,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,MAAM,EAAE,yBAAyB,EAAE,CAAC;CAC/G,CAAC,CAAC;AAGH,uEAAuE;AACvE,+BAA+B;AAC/B,uEAAuE;AAEvE,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,cAAc,EAAE,UAAU;IAC1B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAClC,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE;IACnB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACzB,SAAS,EAAE,iBAAiB;IAC5B,SAAS,EAAE,iBAAiB;CAC7B,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,EAAE,EAAE,UAAU;IACd,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAClC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACzB,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,qBAAqB,CAAC;IACxC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACxC,SAAS,EAAE,iBAAiB;IAC5B,SAAS,EAAE,iBAAiB;CAC7B,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,oBAAoB,GAAG,qBAAqB,CAAC,MAAM,CAAC;IAC/D,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC;CACnC,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IAChC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;CACxD,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC;KACxC,MAAM,CAAC;IACN,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAC3C,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACvD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,QAAQ,EAAE;CACrC,CAAC;KACD,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,8BAA8B,EAAE,CAAC,CAAC;AAGzF,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,kBAAkB,CAAC;IAClC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;CAC1B,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,uBAAuB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9C,cAAc,EAAE,UAAU;IAC1B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CACnC,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,4BAA4B,GAAG,uBAAuB,CAAC;AAGpE,uEAAuE;AACvE,0CAA0C;AAC1C,uEAAuE;AAEvE,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,CAAC,MAAM,CAAC;IACjD,OAAO,EAAE,UAAU;IACnB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;IACf,QAAQ,EAAE,0BAA0B;CACrC,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,EAAE,EAAE,UAAU;IACd,IAAI,EAAE,uBAAuB;IAC7B,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE;IACf,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC7B,CAAC,CAAC;AAGH,MAAM,CAAC,MAAM,2BAA2B,GAAG,CAAC,CAAC,MAAM,CAAC;IAClD,EAAE,EAAE,UAAU;IACd,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,OAAO,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,aAAa,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC;CAC1E,CAAC,CAAC;AAGH,MAAM,oBAAoB,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,EAAE,EAAE,UAAU;IACd,QAAQ,EAAE,UAAU,CAAC,QAAQ,EAAE;IAC/B,IAAI,EAAE,sBAAsB;IAC5B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE;IACjB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAC7C,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC1B,IAAI,EAAE,0BAA0B,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IACtD,OAAO,EAAE,2BAA2B,CAAC,QAAQ,EAAE;IAC/C,KAAK,EAAE,2BAA2B,CAAC,QAAQ,EAAE;IAC7C,KAAK,EAAE,2BAA2B,CAAC,QAAQ,EAAE;IAC7C,SAAS,EAAE,uBAAuB,CAAC,QAAQ,EAAE;CAC9C,CAAC,CAAC;AAMH,MAAM,CAAC,MAAM,sBAAsB,GAAgC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,CAC7E,oBAAoB,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,sBAAsB,CAAC,EAAE,CAAC,CAC3E,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,UAAU,EAAE,UAAU;IACtB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;IAChB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,sBAAsB,CAAC;CACvC,CAAC,CAAC;AAGH,uEAAuE;AACvE,uEAAuE;AACvE,oDAAoD;AACpD,uEAAuE;AAEvE,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,CAAC,MAAM,CAAC;IACpD,SAAS,EAAE,CAAC,CAAC,MAAM,CAAC;QAClB,UAAU,EAAE,UAAU;QACtB,cAAc,EAAE,UAAU;QAC1B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;KACrB,CAAC;IACF,gBAAgB,EAAE,CAAC;SAChB,MAAM,CAAC;QACN,UAAU,EAAE,UAAU;QACtB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE;KACjB,CAAC;SACD,QAAQ,EAAE;CACd,CAAC,CAAC"}

package/dist/meta-ads.d.ts

@@ -0,0 +1,126 @@
+import { z } from 'zod';
+/**
+ * Storefront actions a Meta event can be bound to — one entry per emitter in
+ * `storefront/lib/analytics/ecommerce.ts`. Same closed set as the LinkedIn
+ * module: an operator cannot map an action the storefront never emits.
+ */
+export declare const metaTriggerActionSchema: z.ZodEnum<{
+    contact_form_submitted: "contact_form_submitted";
+    place_order_clicked: "place_order_clicked";
+    add_to_cart: "add_to_cart";
+    add_to_quote_request: "add_to_quote_request";
+    add_to_shopping_list: "add_to_shopping_list";
+    begin_checkout: "begin_checkout";
+    purchase: "purchase";
+    product_viewed: "product_viewed";
+}>;
+export type MetaTriggerAction = z.infer<typeof metaTriggerActionSchema>;
+export declare const META_TRIGGER_ACTIONS: readonly MetaTriggerAction[];
+/**
+ * Meta's documented standard event for each action, or `null` where Meta has no
+ * matching standard name.
+ *
+ * Fixed in code, not operator-editable: Meta's optimisation, catalogue
+ * matching, and ROAS reporting key off these exact names, so letting an
+ * operator rename them would quietly downgrade their reporting. Actions with
+ * `null` still accept a custom mapping — that is what custom mappings are for.
+ */
+export declare const META_STANDARD_EVENTS: Record<MetaTriggerAction, string | null>;
+/** Meta Pixel ID as shown in Events Manager. */
+export declare const metaPixelIdSchema: z.ZodString;
+/** Custom event name: letters, digits, underscore; Meta's practical shape. */
+export declare const metaEventNameSchema: z.ZodString;
+export declare const metaCustomEventMappingSchema: z.ZodObject<{
+    id: z.ZodString;
+    salesChannelId: z.ZodNullable<z.ZodString>;
+    triggerAction: z.ZodEnum<{
+        contact_form_submitted: "contact_form_submitted";
+        place_order_clicked: "place_order_clicked";
+        add_to_cart: "add_to_cart";
+        add_to_quote_request: "add_to_quote_request";
+        add_to_shopping_list: "add_to_shopping_list";
+        begin_checkout: "begin_checkout";
+        purchase: "purchase";
+        product_viewed: "product_viewed";
+    }>;
+    eventName: z.ZodString;
+    enabled: z.ZodBoolean;
+    version: z.ZodNumber;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type MetaCustomEventMapping = z.infer<typeof metaCustomEventMappingSchema>;
+export declare const createMetaCustomEventMappingSchema: z.ZodObject<{
+    salesChannelId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    triggerAction: z.ZodEnum<{
+        contact_form_submitted: "contact_form_submitted";
+        place_order_clicked: "place_order_clicked";
+        add_to_cart: "add_to_cart";
+        add_to_quote_request: "add_to_quote_request";
+        add_to_shopping_list: "add_to_shopping_list";
+        begin_checkout: "begin_checkout";
+        purchase: "purchase";
+        product_viewed: "product_viewed";
+    }>;
+    eventName: z.ZodString;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type CreateMetaCustomEventMapping = z.infer<typeof createMetaCustomEventMappingSchema>;
+export declare const updateMetaCustomEventMappingSchema: z.ZodObject<{
+    salesChannelId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    triggerAction: z.ZodOptional<z.ZodEnum<{
+        contact_form_submitted: "contact_form_submitted";
+        place_order_clicked: "place_order_clicked";
+        add_to_cart: "add_to_cart";
+        add_to_quote_request: "add_to_quote_request";
+        add_to_shopping_list: "add_to_shopping_list";
+        begin_checkout: "begin_checkout";
+        purchase: "purchase";
+        product_viewed: "product_viewed";
+    }>>;
+    eventName: z.ZodOptional<z.ZodString>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    version: z.ZodNumber;
+}, z.core.$strip>;
+export type UpdateMetaCustomEventMapping = z.infer<typeof updateMetaCustomEventMappingSchema>;
+export declare const metaStorefrontMappingSchema: z.ZodObject<{
+    triggerAction: z.ZodEnum<{
+        contact_form_submitted: "contact_form_submitted";
+        place_order_clicked: "place_order_clicked";
+        add_to_cart: "add_to_cart";
+        add_to_quote_request: "add_to_quote_request";
+        add_to_shopping_list: "add_to_shopping_list";
+        begin_checkout: "begin_checkout";
+        purchase: "purchase";
+        product_viewed: "product_viewed";
+    }>;
+    eventName: z.ZodString;
+}, z.core.$strip>;
+export type MetaStorefrontMapping = z.infer<typeof metaStorefrontMappingSchema>;
+export declare const metaStorefrontConfigSchema: z.ZodObject<{
+    enabled: z.ZodBoolean;
+    pixelId: z.ZodNullable<z.ZodString>;
+    requireConsent: z.ZodBoolean;
+    customEvents: z.ZodArray<z.ZodObject<{
+        triggerAction: z.ZodEnum<{
+            contact_form_submitted: "contact_form_submitted";
+            place_order_clicked: "place_order_clicked";
+            add_to_cart: "add_to_cart";
+            add_to_quote_request: "add_to_quote_request";
+            add_to_shopping_list: "add_to_shopping_list";
+            begin_checkout: "begin_checkout";
+            purchase: "purchase";
+            product_viewed: "product_viewed";
+        }>;
+        eventName: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type MetaStorefrontConfig = z.infer<typeof metaStorefrontConfigSchema>;
+/** Fully-off config — the shape every failure path degrades to. */
+export declare const META_DISABLED_CONFIG: MetaStorefrontConfig;
+export declare const META_ADS_SETTING_CODES: {
+    readonly ENABLED: "meta_ads.enabled";
+    readonly PIXEL_ID: "meta_ads.pixel_id";
+    readonly REQUIRE_CONSENT: "meta_ads.require_consent";
+};
+//# sourceMappingURL=meta-ads.d.ts.map

package/dist/meta-ads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-ads.d.ts","sourceRoot":"","sources":["../src/meta-ads.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB;;;;GAIG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;EASlC,CAAC;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAExE,eAAO,MAAM,oBAAoB,EAAE,SAAS,iBAAiB,EAC5B,CAAC;AAElC;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CASzE,CAAC;AAEF,gDAAgD;AAChD,eAAO,MAAM,iBAAiB,aAE2B,CAAC;AAE1D,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,aAEmC,CAAC;AAMpE,eAAO,MAAM,4BAA4B;;;;;;;;;;;;;;;;;;iBAUvC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;iBAK7C,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAE9F,eAAO,MAAM,kCAAkC;;;;;;;;;;;;;;;iBAO7C,CAAC;AACH,MAAM,MAAM,4BAA4B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kCAAkC,CAAC,CAAC;AAM9F,eAAO,MAAM,2BAA2B;;;;;;;;;;;;iBAGtC,CAAC;AACH,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;iBAOrC,CAAC;AACH,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,mEAAmE;AACnE,eAAO,MAAM,oBAAoB,EAAE,oBAKlC,CAAC;AAMF,eAAO,MAAM,sBAAsB;;;;CAIzB,CAAC"}

package/dist/meta-ads.js

@@ -0,0 +1,112 @@
+// Meta Ads module — feature 064 contract surface.
+//
+// Holds the admin custom-event-mapping DTOs, the storefront per-channel config
+// read, the storefront-action enum, the fixed action → Meta standard event map,
+// and `META_ADS_SETTING_CODES`.
+import { z } from 'zod';
+import { isoDateTimeSchema, uuidSchema } from './common.js';
+// ---------------------------------------------------------------------------
+// (1) Enumerations
+// ---------------------------------------------------------------------------
+/**
+ * Storefront actions a Meta event can be bound to — one entry per emitter in
+ * `storefront/lib/analytics/ecommerce.ts`. Same closed set as the LinkedIn
+ * module: an operator cannot map an action the storefront never emits.
+ */
+export const metaTriggerActionSchema = z.enum([
+    'product_viewed',
+    'add_to_cart',
+    'add_to_quote_request',
+    'add_to_shopping_list',
+    'begin_checkout',
+    'place_order_clicked',
+    'purchase',
+    'contact_form_submitted',
+]);
+export const META_TRIGGER_ACTIONS = metaTriggerActionSchema.options;
+/**
+ * Meta's documented standard event for each action, or `null` where Meta has no
+ * matching standard name.
+ *
+ * Fixed in code, not operator-editable: Meta's optimisation, catalogue
+ * matching, and ROAS reporting key off these exact names, so letting an
+ * operator rename them would quietly downgrade their reporting. Actions with
+ * `null` still accept a custom mapping — that is what custom mappings are for.
+ */
+export const META_STANDARD_EVENTS = {
+    product_viewed: 'ViewContent',
+    add_to_cart: 'AddToCart',
+    add_to_quote_request: 'Lead',
+    add_to_shopping_list: null,
+    begin_checkout: 'InitiateCheckout',
+    place_order_clicked: null,
+    purchase: 'Purchase',
+    contact_form_submitted: 'Lead',
+};
+/** Meta Pixel ID as shown in Events Manager. */
+export const metaPixelIdSchema = z
+    .string()
+    .regex(/^[0-9]{1,32}$/, 'Pixel ID must be 1-32 digits');
+/** Custom event name: letters, digits, underscore; Meta's practical shape. */
+export const metaEventNameSchema = z
+    .string()
+    .regex(/^[A-Za-z][A-Za-z0-9_]{0,63}$/, 'Invalid Meta event name');
+// ---------------------------------------------------------------------------
+// (2) Admin DTOs — custom event mappings
+// ---------------------------------------------------------------------------
+export const metaCustomEventMappingSchema = z.object({
+    id: uuidSchema,
+    /** `null` = applies to every sales channel. */
+    salesChannelId: uuidSchema.nullable(),
+    triggerAction: metaTriggerActionSchema,
+    eventName: metaEventNameSchema,
+    enabled: z.boolean(),
+    version: z.number().int().positive(),
+    createdAt: isoDateTimeSchema,
+    updatedAt: isoDateTimeSchema,
+});
+export const createMetaCustomEventMappingSchema = z.object({
+    salesChannelId: uuidSchema.nullable().optional(),
+    triggerAction: metaTriggerActionSchema,
+    eventName: metaEventNameSchema,
+    enabled: z.boolean().optional(),
+});
+export const updateMetaCustomEventMappingSchema = z.object({
+    salesChannelId: uuidSchema.nullable().optional(),
+    triggerAction: metaTriggerActionSchema.optional(),
+    eventName: metaEventNameSchema.optional(),
+    enabled: z.boolean().optional(),
+    /** Current version held by the client — a mismatch is a 409. */
+    version: z.number().int().positive(),
+});
+// ---------------------------------------------------------------------------
+// (3) Storefront config
+// ---------------------------------------------------------------------------
+export const metaStorefrontMappingSchema = z.object({
+    triggerAction: metaTriggerActionSchema,
+    eventName: metaEventNameSchema,
+});
+export const metaStorefrontConfigSchema = z.object({
+    enabled: z.boolean(),
+    /** `null` when unset — a blank Pixel ID means "not configured" (FR-004). */
+    pixelId: z.string().nullable(),
+    requireConsent: z.boolean(),
+    /** Custom events reported *in addition to* the standard event for an action. */
+    customEvents: z.array(metaStorefrontMappingSchema),
+});
+/** Fully-off config — the shape every failure path degrades to. */
+export const META_DISABLED_CONFIG = {
+    enabled: false,
+    pixelId: null,
+    requireConsent: true,
+    customEvents: [],
+};
+// ---------------------------------------------------------------------------
+// (4) Setting codes
+// ---------------------------------------------------------------------------
+export const META_ADS_SETTING_CODES = {
+    ENABLED: 'meta_ads.enabled',
+    PIXEL_ID: 'meta_ads.pixel_id',
+    REQUIRE_CONSENT: 'meta_ads.require_consent',
+};
+//# sourceMappingURL=meta-ads.js.map

package/dist/meta-ads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meta-ads.js","sourceRoot":"","sources":["../src/meta-ads.ts"],"names":[],"mappings":"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"}