# wellpack/counting-contracts

Value objects and enums for the Wellpack **counting model**: pure structures with
no engine logic and no framework dependency. This is the shared PHP source of
truth, consumed by `apps/core-api` (intra-monorepo) and the external
`wellpack/sdk` package.

## Contents

Enums: `Channel`, `ZoneType`, `InterestMode`.
Value objects: `Audience`, `CountOptions`, `CountQuery`, `CountResult`,
`EngineContext`, `InterestGroupSelection`, `InterestSelection`, `Suppressions`,
`Zone`, `ZoneRefinement`.

`CountQuery` is the **canonical** name of the count request (aligned with
core-api; the SDK aligns on it, with no transitional alias).

The package holds **no** engine logic: orchestration and Wepak translation
(`CountingService`, `WepakClient`, `WepakCountPayloadBuilder`) stay in
`apps/core-api`.

## Installation

```bash
composer require wellpack/counting-contracts
```

Requires PHP >= 8.4. No Laravel/Eloquent dependency: usable by any PHP project
(core-api on Laravel 13, the SDK on Laravel 12+) without conflict.

## Versioning

Semver. Any structural change to the model is a version bump:

- patch: internal fixes with no API impact,
- minor: backward-compatible addition (new optional field, new enum value),
- major: breaking change (field rename/removal, semantics).

## Intra-monorepo consumption (path repository)

`apps/core-api` consumes the package locally through a `path` repository
(symlink), without going through a registry:

```jsonc
// apps/core-api/composer.json
"repositories": [
  { "type": "path", "url": "../../packages/counting-contracts", "options": { "symlink": true } }
],
"require": { "wellpack/counting-contracts": "*" }
```

## Publishing (registry)

> Procedure prepared — actual publishing is an external action to trigger
> separately (private registry or Packagist).

1. Make sure `composer check` passes (Pint + Pest).
2. Bump the `version` field (or push a `vX.Y.Z` git tag if the registry derives
   the version from tags).
3. Publish to the target registry:
   - **Private Packagist / composer registry**: declare the repository, push the tag.
   - **Satis / repman**: regenerate the index after tagging.
4. On external consumers (`wellpack/sdk`), replace the `path` repository with the
   published version constraint (`^0.1`) and run `composer update`.

⚠ **Accepted coupling**: publishing from the monorepo couples external SDK
releases to a published version of `counting-contracts`. The TS client
(`@wellpack/core-api-client`) does NOT consume this package (it is generated from
the OpenAPI snapshot): only the PHP world (core-api + SDK) uses it.