# Shop

## Package docs status

This page is generated from package source documentation in `the Capell packages repository` and the checked-in manifest. Source documentation is not distribution status. Before running a Composer command, verify that the exact package and compatible 1.x release are available through public Packagist or the authenticated marketplace account.

| Field | Value |
| --- | --- |
| Composer package | `capell-app/shop` |
| Package slug | `shop` |
| Product group | Capell Commerce |
| Tier | premium |
| Bundle | `commerce` |
| Runtime contexts | `shared` |
| Capell version | `^1.0` |
| Catalogue role | extension |
| Release channel | Beta |
| Source repository | `capell-app/packages` |
| Source path | `packages/shop` |
| Docs source | `packages/shop/docs` |
| Manifest | [`capell.json`](https://github.com/capell-app/packages/edit/main/packages/shop/capell.json) |

<!-- prettier-ignore-start -->

## What This Plugin Adds

Shop is an **Available**, **Schema-owning** Capell package in the **Capell Commerce** product group. It ships as `capell-app/shop` and extends these surfaces: shared.

Shop is the Core-only Capell commerce engine and extension kernel. It provides typed, scoped capability contracts, deterministic ordering and provider-neutral lifecycle boundaries for later commerce surfaces. Runtime receipts and manifest declarations are reconciled through the Core extension contracts.

Later Admin, Storefront, API and provider packages can share one domain engine without importing each other's UI or transport code. The kernel adds no Shop-only public render transport.

Status details:

- Status: Available
- Tier: premium
- Bundle: commerce
- Composer package: `capell-app/shop`
- Namespace: `Capell\Shop`
- Theme key: not applicable

## Why It Matters

**For developers:** Typed capability contracts make context scope, extension ownership and duplicate-key failures explicit before catalogue or payment code lands. Core ordering and source-aware runtime receipts keep registration deterministic and auditable.

**For teams:** Teams can install the commerce engine for headless or physical-retail work without taking on Filament, Frontend or API packages.

## Screens And Workflow

Docs gap: add `docs/screenshots.json` before promoting this package with visual workflow claims.

- Admin index screen if the package has a Filament resource.
- Create/edit screen if editors create records.
- Settings/configuration screen when settings exist.
- Frontend output when the package renders public pages.
- Package detail or install intent screen when marketplace-owned.

## Technical Shape

### Service providers

- `Capell\Shop\Providers\ShopInstallServiceProvider`
- `Capell\Shop\Providers\ShopServiceProvider`

### Migrations

- `packages/shop/database/migrations/2026_09_10_000001_create_shop_idempotency_keys_table.php`
- `packages/shop/database/migrations/2026_09_10_000002_create_shop_outbox_events_table.php`
- `packages/shop/database/migrations/2026_10_04_000001_remove_implicit_timestamp_updates_from_shop_shop_idempotency_keys.php`
- `packages/shop/database/migrations/2026_10_04_000002_remove_implicit_timestamp_updates_from_shop_shop_outbox_events.php`

### Extension contracts

- `ShopAgentToolCapability`
- `ShopCapability`
- `ShopCapabilityManifestContribution`
- `ShopCapabilityProvider`
- `ShopCatalogueCapability`
- `ShopExtension`
- `ShopFulfilmentCapability`
- `ShopIdempotency`
- `ShopInventoryCapability`
- `ShopLifecycleEvent`
- `ShopMerchantOfRecordCapability`
- `ShopOrderLifecycleCapability`
- `ShopOutbox`
- `ShopPaymentCapability`
- `ShopPaymentPurposeCapability`
- `ShopPipelineStage`
- `ShopPricingCapability`
- `ShopPromotionCapability`
- `ShopRiskCapability`
- `ShopSearchCapability`
- `ShopShippingCapability`
- `ShopSurfaceCapability`
- `ShopTaxCapability`

### Actions

- `InstallShopPackageAction`
- `ValidateShopCapabilityManifestAction`

### Data objects

- `ShopApplicabilityData`
- `ShopCapabilityManifestContributionData`
- `ShopCapabilityRegistrationData`
- `ShopCapabilityScopeData`
- `ShopContextData`
- `ShopExtensionRegistrationData`
- `ShopIdempotencyLeaseData`
- `ShopIdempotencyReplayData`
- `ShopIdempotencyRequestData`
- `ShopLifecycleEventData`
- `ShopManifestRuntimeReceiptData`
- `ShopOutboxMessageData`
- `ShopPipelineData`

### Manifest action API

- `install: Capell\Shop\Actions\InstallShopPackageAction`

### Manifest contributions

- `health-check: Capell\Shop\Health\ShopHealthCheck`
- `migration: Capell\Shop\Manifest\ShopMigrationsContribution`

### Health checks

- `Capell\Shop\Health\ShopHealthCheck`

### Cache tags

- `shop`

## Data Model

- Required tables: `shop_idempotency_keys`, `shop_outbox_events`.
- Migration files: `2026_09_10_000001_create_shop_idempotency_keys_table.php`, `2026_09_10_000002_create_shop_outbox_events_table.php`, `2026_10_04_000001_remove_implicit_timestamp_updates_from_shop_shop_idempotency_keys.php`, `2026_10_04_000002_remove_implicit_timestamp_updates_from_shop_shop_outbox_events.php`.
- Migration impact: run host migrations through the package install flow before opening package surfaces.
- Deletion/retention behaviour: Docs gap: migrations and manifest contributions do not prove a cascade, pruning command, or timed retention policy.

## Install Impact

- Required packages: `capell-app/core`.
- Admin navigation: no admin page or resource contribution is declared.
- Admin/editor extensions: none declared.
- Permissions: no package permission declarations or Shield gates detected; host access rules still apply.
- Public routes: none declared.
- Database changes: package migrations are declared.
- Config: no package config files.
- Settings: no package settings declared.
- Queues or schedules: none declared.
- Cache tags: `shop`.
- Commands: none declared.

## Common Pitfalls

- Keep required Capell packages on compatible v4 releases: `capell-app/core`.
- Run migrations before opening package resources or public routes.
- Custom write integrations must preserve invalidation for `shop` cache tags.

## Troubleshooting

| Symptom | Likely cause | Check | Fix |
| --- | --- | --- | --- |
| Package surface is missing after install | Provider or manifest is not loaded | Confirm `capell.json`, package `composer.json`, and provider registration | Reinstall the package, refresh Composer autoload, and clear host caches |
| Admin screen or command fails on missing table | Package migrations have not run | Check the tables listed in `Data Model` | Run host migrations and rerun the focused package test |

## Quick Start

1. Install the package: `composer require capell-app/shop`.
2. Verify the package provider and manifest contributions are registered in the host app.

## Upgrading

No manual steps between minor versions.

Read [CHANGELOG.md](CHANGELOG.md) before upgrading.

## Next Steps

- [Package docs](README.md)
- [Overview](overview.md)
- [Worked extension examples](extension-contracts.md)
- [Troubleshooting](#troubleshooting)
- [Screenshot contract](screenshots.json)
- [Marketplace assets](assets/marketplace/)
- [Capell content language plan](../../docs/CONTENT_LANGUAGE_PLAN.md)
- [Capell documentation design system](../../docs/DESIGN_SYSTEM.md)
- [Capell and package ERD notes](../../docs/erd/capell-and-package-erds.md)

<!-- prettier-ignore-end -->