@endora-commerce/mod-meta-ads 0.0.0-stage → 0.100.0

package/dist/manifest.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Meta Ads module (feature 064). Puts the Meta Pixel on the storefront per sales
+ * channel, reports Meta's standard commerce events, and lets an operator add
+ * custom events alongside them.
+ *
+ * Per-channel configuration is stored through the Settings module. Server-side
+ * reporting through Meta's Conversions API is deliberately out of v1 — see
+ * specs/064-meta-ads/research.md §R7.
+ */
+export declare const metaAdsSettingsManifest: {
+    moduleCode: string;
+    groups: {
+        code: string;
+        name: string;
+        salesChannelCodes?: string[] | undefined;
+        isSystemProtected?: boolean | undefined;
+    }[];
+    settings: {
+        code: string;
+        name: string;
+        valueType: "string" | "number" | "boolean" | "json" | "string_list" | "secret" | "credential_ref";
+        defaultValue: unknown;
+        description?: string | undefined;
+        groupCode?: string | undefined;
+        previousDefaultValues?: unknown[] | undefined;
+        salesChannelCodes?: string[] | undefined;
+        enumOptions?: string[] | undefined;
+        configurationType?: string | undefined;
+        hidden?: boolean | undefined;
+    }[];
+};
+export declare const META_ADS_READ_PERMISSION = "meta_ads:read";
+export declare const META_ADS_WRITE_PERMISSION = "meta_ads:write";
+export declare const manifest: {
+    id: string;
+    name: string;
+    version: string;
+    dependencies: string[];
+    description?: string | undefined;
+    acknowledgedDependencies?: {
+        moduleId: string;
+        port: string;
+        reason: string;
+    }[] | undefined;
+    nonBindingDependencies?: {
+        moduleId: string;
+        name: string;
+        kind: "contributes-to" | "degrades-without" | "refuses-without";
+        reason: string;
+        whenAbsent?: string | undefined;
+    }[] | undefined;
+    activation?: {
+        settingCode: string;
+        default: boolean;
+    } | {
+        nonDeactivatable: true;
+        reason: string;
+    } | undefined;
+    settings?: {
+        moduleCode: string;
+        groups: {
+            code: string;
+            name: string;
+            salesChannelCodes?: string[] | undefined;
+            isSystemProtected?: boolean | undefined;
+        }[];
+        settings: {
+            code: string;
+            name: string;
+            valueType: "string" | "number" | "boolean" | "json" | "string_list" | "secret" | "credential_ref";
+            defaultValue: unknown;
+            description?: string | undefined;
+            groupCode?: string | undefined;
+            previousDefaultValues?: unknown[] | undefined;
+            salesChannelCodes?: string[] | undefined;
+            enumOptions?: string[] | undefined;
+            configurationType?: string | undefined;
+            hidden?: boolean | undefined;
+        }[];
+    } | undefined;
+    i18n?: {
+        bundlesDir: string;
+    } | undefined;
+    docs?: false | {
+        dir: string;
+    } | undefined;
+    demo?: false | {
+        summary: string;
+        seed: (context: import("@endora-commerce/contracts").ModuleDemoContext<never>) => Promise<import("@endora-commerce/contracts").DemoSeedResult>;
+        reset: (context: import("@endora-commerce/contracts").ModuleDemoContext<never>) => Promise<import("@endora-commerce/contracts").DemoResetResult>;
+        after?: readonly string[] | undefined;
+        package?: string | undefined;
+    } | undefined;
+    actions?: {
+        id: string;
+        labelKey: string;
+        icon: "Plus" | "Sparkles" | "Settings" | "Search" | "Boxes" | "Layers" | "Menu" | "PlusCircle" | "PlusSquare" | "FilePlus" | "FolderPlus" | "Upload" | "FileUp" | "CloudUpload" | "Download" | "FileDown" | "FileText" | "BookOpen" | "Rss" | "Package" | "Tag" | "ShoppingCart" | "Receipt" | "CreditCard" | "Users" | "UserPlus" | "Inbox" | "ListChecks" | "ClipboardList" | "Image" | "Video" | "LayoutDashboard" | "PanelLeft" | "KeyRound" | "ShieldCheck" | "Edit" | "Archive" | "Box" | "Truck" | "CircleDollarSign" | "Activity" | "LineChart" | "Smartphone" | "Webhook" | "Scale" | "PlugZap" | "PercentDiamond" | "Newspaper" | "Languages" | "Eraser" | "Warehouse" | "TrendingDown" | "Bell" | "PackageOpen" | "Building2" | "Store" | "ClipboardCheck";
+        targetRoute: string;
+        keywords: string[];
+        weight: number;
+        descriptionKey?: string | undefined;
+        requiredPermission?: string | undefined;
+    }[] | undefined;
+    permissions?: {
+        code: string;
+        label: string;
+        module?: string | undefined;
+        description?: string | undefined;
+        requires?: string[] | undefined;
+    }[] | undefined;
+    transactionalEmails?: {
+        code: string;
+        name: string;
+        variables: {
+            key: string;
+            label: string;
+            sampleValue?: string | undefined;
+            description?: string | undefined;
+        }[];
+        description?: string | undefined;
+        group?: string | undefined;
+    }[] | undefined;
+    capabilities?: string[] | undefined;
+    exclusiveCapabilities?: {
+        key: string;
+        errorCode: string;
+    }[] | undefined;
+    errorCodes?: {
+        code: string;
+        tokens?: string[] | undefined;
+    }[] | undefined;
+    blocks?: {
+        name: string;
+        labelKey: string;
+        category: string;
+        contexts: ("invoice" | "email" | "cms" | "newsletter")[];
+        fields: Record<string, {
+            type: "number" | "object" | "array" | "text" | "textarea" | "select" | "radio" | "external" | "uuid" | "richtext";
+            label?: string | undefined;
+            required?: boolean | undefined;
+            options?: {
+                label: string;
+                value: string | number;
+            }[] | undefined;
+            refKind?: string | undefined;
+        }>;
+        descriptionKey?: string | undefined;
+        defaultProps?: Record<string, unknown> | undefined;
+        responsiveFields?: string[] | undefined;
+        previewIcon?: string | undefined;
+        weight?: number | undefined;
+    }[] | undefined;
+    blockCategories?: {
+        key: string;
+        titleKey: string;
+        contexts: ("invoice" | "email" | "cms" | "newsletter")[];
+        weight?: number | undefined;
+        visible?: boolean | undefined;
+    }[] | undefined;
+    env?: {
+        name: string;
+        describes: {
+            en: string;
+            pl: string;
+        };
+        requirement: {
+            kind: "required";
+        } | {
+            kind: "requiredWhen";
+            input: string;
+            equals: string;
+        } | {
+            kind: "optional";
+            without: {
+                en: string;
+                pl: string;
+            };
+        };
+        secret: boolean;
+        generable: boolean;
+        owner: {
+            kind: "platform";
+        } | {
+            kind: "application";
+            application: "admin" | "backend" | "storefront";
+        } | {
+            kind: "module";
+            moduleId: string;
+        };
+        consumers: ("admin" | "backend" | "storefront")[];
+        addressOf: "admin" | "backend" | "storefront" | null;
+    }[] | undefined;
+};
+//# sourceMappingURL=manifest.d.ts.map

package/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;CAgDlC,CAAC;AAEH,eAAO,MAAM,wBAAwB,kBAAkB,CAAC;AACxD,eAAO,MAAM,yBAAyB,mBAAmB,CAAC;AAE1D,eAAO,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0CnB,CAAC"}

package/dist/manifest.js

@@ -0,0 +1,102 @@
+import { defineModuleManifest, defineModuleSettingsManifest } from '@endora-commerce/contracts';
+import { META_ADS_SETTING_CODES } from '@endora-commerce/contracts';
+/**
+ * Meta Ads module (feature 064). Puts the Meta Pixel on the storefront per sales
+ * channel, reports Meta's standard commerce events, and lets an operator add
+ * custom events alongside them.
+ *
+ * Per-channel configuration is stored through the Settings module. Server-side
+ * reporting through Meta's Conversions API is deliberately out of v1 — see
+ * specs/064-meta-ads/research.md §R7.
+ */
+export const metaAdsSettingsManifest = defineModuleSettingsManifest({
+    moduleCode: 'meta_ads',
+    groups: [{ code: 'meta_ads', name: 'Meta Ads' }],
+    settings: [
+        {
+            // Feature 073 — the operator's activation control. **Platform-wide, and
+            // deliberately NOT `meta_ads.enabled`.** That code already exists and
+            // means something else: it is per-sales-channel and answers "is the
+            // pixel is live on a given storefront channel". This one answers "does this client have the Meta Ads
+            // capability at all". Adopting the existing code would have collapsed two
+            // orthogonal questions into one switch — and, because an activation
+            // control may only be written through the activation endpoint, would have
+            // made the per-channel setting unwritable through the settings screen.
+            code: 'meta_ads.module_enabled',
+            name: 'Meta Ads module enabled',
+            description: 'Switches Meta Pixel injection, the custom-event mappings and the admin screen on or off for the whole platform. Separate from the per-channel switch, which decides where the tag actually loads. Nothing is dropped: mappings stay in the database and every setting keeps its value.',
+            groupCode: 'meta_ads',
+            valueType: 'boolean',
+            defaultValue: true,
+        },
+        {
+            code: META_ADS_SETTING_CODES.ENABLED,
+            name: 'Enable Meta Ads',
+            description: 'Master switch for the module. Per-channel overridable.',
+            groupCode: 'meta_ads',
+            valueType: 'boolean',
+            defaultValue: false,
+        },
+        {
+            code: META_ADS_SETTING_CODES.PIXEL_ID,
+            name: 'Pixel ID',
+            description: 'Meta Pixel ID from Events Manager. Blank means the channel is untracked.',
+            groupCode: 'meta_ads',
+            valueType: 'string',
+            defaultValue: '',
+        },
+        {
+            code: META_ADS_SETTING_CODES.REQUIRE_CONSENT,
+            name: 'Require analytics consent',
+            description: 'When enabled, nothing Meta-related runs until the visitor accepts the cookie banner.',
+            groupCode: 'meta_ads',
+            valueType: 'boolean',
+            defaultValue: true,
+        },
+    ],
+});
+export const META_ADS_READ_PERMISSION = 'meta_ads:read';
+export const META_ADS_WRITE_PERMISSION = 'meta_ads:write';
+export const manifest = defineModuleManifest({
+    id: 'meta_ads',
+    name: 'Meta Ads',
+    description: 'Meta Ads integration: per-sales-channel Meta Pixel, consent-gated tracking, standard commerce events, and configurable custom events.',
+    version: '1.0.0',
+    // `auth` owns the `requireAdmin` port the admin routes are gated by; feature
+    // 072 made it a container resolution rather than a constructor argument.
+    dependencies: ['audit_logs', 'sales_channels', 'settings', 'auth'],
+    settings: metaAdsSettingsManifest,
+    i18n: { bundlesDir: 'i18n' },
+    docs: { dir: 'docs' },
+    permissions: [
+        { code: META_ADS_READ_PERMISSION, label: 'View Meta Ads configuration' },
+        {
+            code: META_ADS_WRITE_PERMISSION,
+            label: 'Manage Meta Ads configuration and custom events',
+        },
+    ],
+    actions: [
+        {
+            id: 'open-meta-ads',
+            labelKey: 'actions.openMetaAds.label',
+            descriptionKey: 'actions.openMetaAds.description',
+            icon: 'Sparkles',
+            targetRoute: '/meta-ads',
+            requiredPermission: META_ADS_READ_PERMISSION,
+            keywords: ['meta', 'facebook', 'instagram', 'pixel', 'ads', 'reklamy'],
+            weight: 244,
+        },
+        {
+            id: 'new-meta-custom-event',
+            labelKey: 'actions.newCustomEvent.label',
+            descriptionKey: 'actions.newCustomEvent.description',
+            icon: 'Plus',
+            targetRoute: '/meta-ads/new',
+            requiredPermission: META_ADS_WRITE_PERMISSION,
+            keywords: ['meta', 'pixel', 'event', 'zdarzenie', 'custom'],
+            weight: 245,
+        },
+    ],
+    activation: { settingCode: 'meta_ads.module_enabled', default: true },
+});
+//# sourceMappingURL=manifest.js.map

package/dist/manifest.js.map

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

package/dist/migrations/20260728T002715_meta_ads_init.d.ts

@@ -0,0 +1,12 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * Feature 064 — Meta Ads. Creates `meta_custom_event_mappings`.
+ *
+ * Channel configuration (enabled, pixel id, consent) lives in the Settings
+ * module and needs no schema here.
+ */
+export declare class Migration20260728T002715MetaAdsInit extends Migration {
+    up(): Promise<void>;
+    down(): Promise<void>;
+}
+//# sourceMappingURL=20260728T002715_meta_ads_init.d.ts.map

package/dist/migrations/20260728T002715_meta_ads_init.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260728T002715_meta_ads_init.d.ts","sourceRoot":"","sources":["../../src/migrations/20260728T002715_meta_ads_init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;GAKG;AACH,qBAAa,mCAAoC,SAAQ,SAAS;IACjD,EAAE,IAAI,OAAO,CAAC,IAAI,CAAC;IAyBnB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAGrC"}

package/dist/migrations/20260728T002715_meta_ads_init.js

@@ -0,0 +1,35 @@
+import { Migration } from '@mikro-orm/migrations';
+/**
+ * Feature 064 — Meta Ads. Creates `meta_custom_event_mappings`.
+ *
+ * Channel configuration (enabled, pixel id, consent) lives in the Settings
+ * module and needs no schema here.
+ */
+export class Migration20260728T002715MetaAdsInit extends Migration {
+    async up() {
+        this.addSql(`
+      create table "meta_custom_event_mappings" (
+        "id" uuid not null,
+        "sales_channel_id" uuid null,
+        "trigger_action" varchar(32) not null,
+        "event_name" varchar(64) not null,
+        "enabled" boolean not null default true,
+        "version" int not null default 1,
+        "created_at" timestamptz not null,
+        "updated_at" timestamptz not null,
+        constraint "meta_custom_event_mappings_pkey" primary key ("id")
+      );
+    `);
+        this.addSql(`
+      alter table "meta_custom_event_mappings"
+        add constraint "meta_custom_event_mappings_sales_channel_id_foreign"
+          foreign key ("sales_channel_id") references "sales_channels" ("id")
+          on update cascade on delete cascade;
+    `);
+        this.addSql('create index "meta_custom_event_mappings_channel_action_idx" on "meta_custom_event_mappings" ("sales_channel_id", "trigger_action");');
+    }
+    async down() {
+        this.addSql('drop table if exists "meta_custom_event_mappings" cascade;');
+    }
+}
+//# sourceMappingURL=20260728T002715_meta_ads_init.js.map

package/dist/migrations/20260728T002715_meta_ads_init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"20260728T002715_meta_ads_init.js","sourceRoot":"","sources":["../../src/migrations/20260728T002715_meta_ads_init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAElD;;;;;GAKG;AACH,MAAM,OAAO,mCAAoC,SAAQ,SAAS;IACvD,KAAK,CAAC,EAAE;QACf,IAAI,CAAC,MAAM,CAAC;;;;;;;;;;;;KAYX,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CAAC;;;;;KAKX,CAAC,CAAC;QACH,IAAI,CAAC,MAAM,CACT,sIAAsI,CACvI,CAAC;IACJ,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,IAAI,CAAC,MAAM,CAAC,4DAA4D,CAAC,CAAC;IAC5E,CAAC;CACF"}

package/dist/migrations/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent (D-168).
+ *
+ * Listed in ascending timestamp, which is the order of this module's own
+ * migrations and of nothing else (feature 081): a manifest `dependencies` array
+ * is the only thing ordering this block against another module's.
+ *
+ * The **named** exports stay beside the array, and the asymmetry with
+ * `./backend` — which publishes an array and no named class (D-168) — is
+ * deliberate. `db/migrations-registry.generated.ts` imports each class by name
+ * from this specifier, and a migration class name is contract in a way an entity
+ * class name is not: `mikro_orm_migrations` persists it, so it is a string every
+ * already-migrated database holds.
+ *
+ * A class that is in neither the array nor the barrel is a migration that does
+ * not run: `migration:pending` reports nothing pending and the first symptom is
+ * a query against a table nobody created.
+ */
+import { Migration20260728T002715MetaAdsInit } from './20260728T002715_meta_ads_init.js';
+export declare const migrations: (typeof Migration20260728T002715MetaAdsInit)[];
+export { Migration20260728T002715MetaAdsInit, };
+//# sourceMappingURL=index.d.ts.map

package/dist/migrations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,mCAAmC,EAAE,MAAM,oCAAoC,CAAC;AAEzF,eAAO,MAAM,UAAU,gDAEtB,CAAC;AAEF,OAAO,EACL,mCAAmC,GACpC,CAAC"}

package/dist/migrations/index.js

@@ -0,0 +1,29 @@
+/**
+ * The `./migrations` subpath — every migration class this module owns, as one
+ * ordered `migrations` array.
+ *
+ * The array is what the platform reads when this module is **installed**:
+ * `src/packages/package-runtime.ts` takes `exported['migrations']` and refuses
+ * the package outright when it is absent (D-168).
+ *
+ * Listed in ascending timestamp, which is the order of this module's own
+ * migrations and of nothing else (feature 081): a manifest `dependencies` array
+ * is the only thing ordering this block against another module's.
+ *
+ * The **named** exports stay beside the array, and the asymmetry with
+ * `./backend` — which publishes an array and no named class (D-168) — is
+ * deliberate. `db/migrations-registry.generated.ts` imports each class by name
+ * from this specifier, and a migration class name is contract in a way an entity
+ * class name is not: `mikro_orm_migrations` persists it, so it is a string every
+ * already-migrated database holds.
+ *
+ * A class that is in neither the array nor the barrel is a migration that does
+ * not run: `migration:pending` reports nothing pending and the first symptom is
+ * a query against a table nobody created.
+ */
+import { Migration20260728T002715MetaAdsInit } from './20260728T002715_meta_ads_init.js';
+export const migrations = [
+    Migration20260728T002715MetaAdsInit,
+];
+export { Migration20260728T002715MetaAdsInit, };
+//# sourceMappingURL=index.js.map

package/dist/migrations/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/migrations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,mCAAmC,EAAE,MAAM,oCAAoC,CAAC;AAEzF,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,mCAAmC;CACpC,CAAC;AAEF,OAAO,EACL,mCAAmC,GACpC,CAAC"}

package/docs/meta-ads.md

@@ -0,0 +1,82 @@
+---
+title: Meta Ads
+description: Meta Pixel per sales channel, with the standard commerce events and optional custom events on top
+---
+
+# Meta Ads
+
+Puts the **Meta Pixel** on the storefront per sales channel and reports Meta's standard commerce
+events, with optional custom events on top.
+
+Module id `meta_ads`.
+
+## Configuration (Settings module)
+
+All values live in the **Meta Ads** settings group and are overridable per sales channel.
+
+| Setting | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `meta_ads.enabled` | boolean | `false` | Master switch for the channel. |
+| `meta_ads.pixel_id` | string | `''` | Pixel ID from Events Manager. |
+| `meta_ads.require_consent` | boolean | `true` | Gate all Meta behaviour on the cookie-banner decision. |
+
+A channel is tracked only when the master switch is on **and** the Pixel ID is non-blank. A blank
+Pixel ID is "not configured", never an error the visitor sees, so clearing it is a safe way to pause
+a channel.
+
+## Storefront behaviour
+
+The Pixel loads asynchronously and never blocks the first paint. Nothing Meta-related runs — no
+script, no cookie, no request — until the visitor accepts the cookie banner, unless the operator has
+turned the consent requirement off. A visitor who accepts mid-session is tracked from that moment
+without a reload.
+
+Consent is the storefront's single decision, shared with Google Analytics and LinkedIn Ads, so there
+is only ever one banner and one stored answer. Each platform gates independently: turning Meta on or
+off does not affect the others.
+
+## Standard events
+
+These fire automatically for the storefront actions the platform already emits, with the parameters
+Meta expects for catalogue matching and ROAS reporting:
+
+| Storefront action | Meta event |
+| --- | --- |
+| Product viewed | `ViewContent` |
+| Added to cart | `AddToCart` |
+| Checkout started | `InitiateCheckout` |
+| Order completed | `Purchase` |
+| Added to quote request | `Lead` |
+| Contact form submitted | `Lead` |
+| Added to shopping list | *(none)* |
+| Place Order clicked | *(none)* |
+
+Names are fixed in code, not editable — Meta's optimisation and catalogue matching key off these
+exact names, so renaming them would quietly downgrade your reporting.
+
+## Custom events
+
+Under **Admin → Meta Ads** you can report any of those storefront actions under your own event name
+too — for example, "added to quote request" as `SubmitQuote` for a B2B-specific audience.
+
+A custom event is **additive**: the standard event still fires, and yours fires beside it. It never
+replaces the standard event, so adding an audience event cannot cost you your `Purchase` reporting.
+The two actions with no standard event accept custom mappings, which is exactly what they are for.
+
+A mapping can target one sales channel or all of them, and can be disabled without deleting it.
+
+## Permissions
+
+| Code | Grants |
+| --- | --- |
+| `meta_ads:read` | View custom events and the module page. |
+| `meta_ads:write` | Create, edit, and delete custom events. |
+
+Both appear on `/admin-roles`. Changes are audited with the acting operator.
+
+## Not yet implemented
+
+- **Conversions API (server-side reporting).** Browser pixels are heavily ad-blocked, so expect
+  reported conversions to under-count until this lands. It needs an access token and an event ID
+  shared with the browser event for deduplication, and is worth doing once for both ad platforms.
+- **Conversion retraction** for refunded or cancelled orders.

package/i18n/en.json

@@ -0,0 +1,35 @@
+{
+  "actions.openMetaAds.label": "Meta Ads",
+  "actions.openMetaAds.description": "Configure Meta Pixel custom events",
+  "actions.newCustomEvent.label": "New Meta custom event",
+  "actions.newCustomEvent.description": "Report a storefront action as a custom Meta event",
+  "nav.metaAds.label": "Meta Ads",
+  "customEvents.title": "Custom events",
+  "customEvents.subtitle": "Report a storefront action under your own Meta event name. Standard events (ViewContent, AddToCart, Purchase…) are always reported and are not affected by these.",
+  "customEvents.empty": "No custom events yet",
+  "customEvents.new": "New custom event",
+  "customEvents.edit": "Edit custom event",
+  "customEvents.triggerAction": "Storefront action",
+  "customEvents.eventName": "Meta event name",
+  "customEvents.eventNameHint": "Letters, digits and underscores, e.g. SubmitQuote.",
+  "customEvents.standardEvent": "Standard event",
+  "customEvents.standardEventNone": "none",
+  "customEvents.salesChannel": "Sales channel",
+  "customEvents.allChannels": "All channels",
+  "customEvents.enabled": "Enabled",
+  "customEvents.save": "Save",
+  "customEvents.delete": "Delete",
+  "customEvents.deleteConfirm": "Delete this custom event?",
+  "customEvents.action.product_viewed": "Product viewed",
+  "customEvents.action.add_to_cart": "Added to cart",
+  "customEvents.action.add_to_quote_request": "Added to quote request",
+  "customEvents.action.add_to_shopping_list": "Added to shopping list",
+  "customEvents.action.begin_checkout": "Checkout started",
+  "customEvents.action.place_order_clicked": "Place Order clicked",
+  "customEvents.action.purchase": "Order completed",
+  "customEvents.action.contact_form_submitted": "Contact form submitted",
+  "error.generic": "Something went wrong.",
+  "error.notFound": "Custom event not found.",
+  "error.versionConflict": "Someone else changed this custom event. Reload and reapply your edit.",
+  "error.validationFailed": "Some fields are invalid."
+}

package/i18n/pl.json

@@ -0,0 +1,35 @@
+{
+  "actions.openMetaAds.label": "Meta Ads",
+  "actions.openMetaAds.description": "Konfiguruj własne zdarzenia Meta Pixel",
+  "actions.newCustomEvent.label": "Nowe zdarzenie własne Meta",
+  "actions.newCustomEvent.description": "Raportuj akcję w Storefront jako własne zdarzenie Meta",
+  "nav.metaAds.label": "Meta Ads",
+  "customEvents.title": "Zdarzenia własne",
+  "customEvents.subtitle": "Raportuj akcję w Storefront pod własną nazwą zdarzenia Meta. Zdarzenia standardowe (ViewContent, AddToCart, Purchase…) są wysyłane zawsze i nie zależą od tych ustawień.",
+  "customEvents.empty": "Brak zdarzeń własnych",
+  "customEvents.new": "Nowe zdarzenie własne",
+  "customEvents.edit": "Edytuj zdarzenie własne",
+  "customEvents.triggerAction": "Akcja w Storefront",
+  "customEvents.eventName": "Nazwa zdarzenia Meta",
+  "customEvents.eventNameHint": "Litery, cyfry i podkreślenia, np. SubmitQuote.",
+  "customEvents.standardEvent": "Zdarzenie standardowe",
+  "customEvents.standardEventNone": "brak",
+  "customEvents.salesChannel": "Kanał sprzedaży",
+  "customEvents.allChannels": "Wszystkie kanały",
+  "customEvents.enabled": "Aktywne",
+  "customEvents.save": "Zapisz",
+  "customEvents.delete": "Usuń",
+  "customEvents.deleteConfirm": "Usunąć to zdarzenie własne?",
+  "customEvents.action.product_viewed": "Wyświetlenie produktu",
+  "customEvents.action.add_to_cart": "Dodanie do koszyka",
+  "customEvents.action.add_to_quote_request": "Dodanie do zapytania ofertowego",
+  "customEvents.action.add_to_shopping_list": "Dodanie do listy zakupowej",
+  "customEvents.action.begin_checkout": "Rozpoczęcie zamówienia",
+  "customEvents.action.place_order_clicked": "Kliknięcie „Złóż zamówienie”",
+  "customEvents.action.purchase": "Złożenie zamówienia",
+  "customEvents.action.contact_form_submitted": "Zapis formularza kontaktowego",
+  "error.generic": "Coś poszło nie tak.",
+  "error.notFound": "Nie znaleziono zdarzenia własnego.",
+  "error.versionConflict": "Ktoś inny zmienił to zdarzenie. Odśwież stronę i ponów zmianę.",
+  "error.validationFailed": "Niektóre pola są nieprawidłowe."
+}