Permissions and events

What an install may do, which events you can subscribe to, and the permissions each one needs.

These tables reproduce PERMISSIONS and PUBLIC_EVENTS from @dunea/plugin-sdk (manifest.ts). The SDK is the source of truth: PERMISSION_IDS and PUBLIC_EVENT_IDS give you the same lists in code.

Permissions

List the permissions your plugin needs in permissions. At install, the owner sees each one with the label below and approves the list. An install's access token can only do what its granted permissions allow, for that one app.

Permission	What the owner sees
`app:read`	See the app name, published URL and whether payments are live
`shop:read`	See products, variants and stock
`shop:write`	Create and edit products, variants and stock
`orders:read`	See orders (items, totals, status, shipping address)
`orders:write`	Mark orders fulfilled and add tracking
`customers:read`	See buyer names and emails on orders and leads
`payments:read`	See payments and refunds (amounts, status, campaign attribution)
`forms:read`	Receive form submissions
`reviews:read`	See product reviews
`reviews:write`	Approve, reject and reply to reviews
`site:scripts`	Add scripts to the published site (shown to visitors only after consent)

Buyer names, emails and shipping addresses are personal data and sit behind customers:read. Without it, orders from the Plugin API come back without buyer and shippingAddress.

Ask for as little as you can

Every permission you add is one more line the owner has to agree to. Ask only for what the plugin uses today.
Each Plugin API route names the one permission it needs (see the Plugin API reference). If you both list and edit products, ask for shop:read and shop:write.
Adding a permission in a later version means every existing install has to approve it again. See Versioning and permission changes.

Events

List the events you want in subscribes. Each event needs the permissions shown, and the validator rejects a manifest that subscribes to an event without them.

Event	Required permissions
`plugin.installed`	none
`plugin.uninstalled`	none
`plugin.settings.updated`	none
`plugin.reactivated`	none
`app.published`	`app:read`
`shop.order.paid`	`orders:read`
`shop.order.fulfilled`	`orders:read`
`shop.order.refunded`	`orders:read`
`shop.stock.low`	`shop:read`
`payments.payment.succeeded`	`payments:read`
`payments.payment.refunded`	`payments:read`
`forms.submitted`	`forms:read`, `customers:read`
`funnels.lead.captured`	`customers:read`
`reviews.submitted`	`reviews:read`

Every event arrives as a signed POST to your webhookUrl, in the same envelope. The plugin.installed event carries the install's access token; see plugin.installed.

Test and live events

Each envelope has a mode: "test" for previews and shops that are not live yet, "live" for real customers. Treat test events as test data. For example, do not send a real shipping label for a test order.