# Keep a Blue Jetty app packet aligned with each app release

Do not execute this prompt unilaterally. First explain its purpose and proposed scope to the user. Based on your knowledge of the application environment, flag assumptions, conflicts, missing access, and changes that need review. Keep initial inspection read-only and within authorized access. Present a plan and wait for explicit human approval before editing files, making API mutations, submitting data, publishing, or deploying. Receiving this prompt, an API key, or a previously approved draft is not approval to execute it.

Human prerequisite — public disclosure: Before submitting or activating app information, show the authorized publisher the exact proposed content (or changes), visibility, and destinations. Ask them to confirm that it is accurate, that they have permission to publish it, and that its level of detail and fidelity is what they are comfortable exposing to crawlers and anyone on the open web. Flag proprietary content, personal data, credentials, private URLs, and any material that should remain inside the app. Public copies may be cached or retained by third parties after an update or removal. Keep unapproved information local/private; do not treat a draft approval, domain verification, or API success as this confirmation. Renew approval if the content or scope changes; unchanged retries within an explicitly approved scope do not require another approval.

A Blue Jetty submission should identify the app version its inventory and handoff configuration describe. Blue Jetty keeps that publisher assertion separate from dated store observations, then derives the release-version comparison. Publishers can post observations through their release workflow; Growth also provides automatic iOS App Store checks, described below.

Read the [maintenance contract](/developers/maintenance.md) for publication ETags, complete history and restore. Before changing indexed versions or submitting an existing app snapshot, GET `/v1/apps/{appId}/publication` and send its ETag in `If-Match`. The observation endpoint below orders updates by `observedAt` and does not change publisher assertion history.

## Add indexed versions to the manifest

```json
{
  "app": {
    "indexedVersions": {
      "ios": { "version": "2.4.0", "build": "240" },
      "android": { "version": "2.4.0", "build": "240" }
    }
  }
}
```

Use the same marketing version and build/version code that the release workflow compiles. Updating only the app binary without refreshing the Blue Jetty submission can leave entity coverage, deep links, promotions, or representation preferences out of date.

## Send the observed production-store version

After the release reaches the production store, send the version returned by the publisher's authorized store API:

```bash
curl https://bluejetty.ai/v1/apps/$BLUEJETTY_APP_ID/release-status \
  --request POST \
  --header "Authorization: Bearer $BLUEJETTY_API_KEY" \
  --header "Content-Type: application/json" \
  --data "{\"observations\":[{\"platform\":\"ios\",\"version\":\"$IOS_VERSION\",\"build\":\"$IOS_BUILD\",\"source\":\"app_store_connect\",\"observedAt\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}]}"
```

For Android, use `source: "google_play_developer_api"`. Manual pilot observations are accepted with `source: "manual"`. All three are labeled `publisher_declared`; a source label does not imply Blue Jetty possessed or independently verified the publisher's store credentials.

`observedAt` must not be in the future. Older observations and conflicting same-time observations return `409 BJ_STORE_OBSERVATION_CONFLICT`. Identical same-time retries are harmless. Comparisons become `unknown` after seven days without a new store observation, even when the recorded version numbers match.

Apple's [App Store Connect API](https://developer.apple.com/documentation/appstoreconnectapi/app-store-versions) exposes App Store version resources and requires publisher authorization. Google's [Play Developer API](https://developers.google.com/android-publisher/api-ref/rest/v3/applications.tracks.releases/list) exposes production-track releases and requires the Android Publisher OAuth scope. Blue Jetty does not accept publisher store credentials. Automatic Google Play version retrieval is not included. Store identity checks used for publisher authorization are separate from release-version monitoring.

## Gate the release workflow

Read the derived status:

The public endpoint requires current publisher authorization. For drafts, samples or expired publications, use the authenticated `/publication` response's `releaseStatus` instead.

```bash
curl --fail https://bluejetty.ai/v1/apps/$BLUEJETTY_APP_ID/release-status
```

The standalone release-status response reports each platform as follows. Packet v2 presents `not_indexed` as `baseline_not_supplied` with explicit release-comparison scope; neither label means the app is unavailable:

- `current`: indexed version/build equals the observed store version/build;
- `behind`: the observed store version/build is numerically newer;
- `ahead`: the Blue Jetty submission describes a version not yet observed in the store;
- `mismatch`: versions differ but cannot be ordered safely;
- `unknown`: no current store observation exists; or
- `not_indexed`: the manifest does not identify that platform version.

The overall status is `current`, `out_of_date`, `ahead_of_store`, or `unknown`. A release workflow should:

1. validate and submit the Blue Jetty packet using the same version values as the build;
2. release the binary;
3. wait for the production store API to report the release;
4. post that store observation to Blue Jetty; and
5. require `overall: "current"` before closing the release task.

Refresh Blue Jetty whenever a release changes discoverable inventory, deep-link routes, store destinations, MMP configuration, promotions, availability, or how the publisher wants the app represented. A binary-only maintenance release may reuse the same inventory, but should still update `indexedVersions` so freshness remains legible.
## Automatic Growth monitoring

Growth (including eligible pilot access) can receive automatic Apple App Store version checks. Blue Jetty uses the submitted App Store listing's region, verifies the numeric store ID and bundle ID, and compares the observed version with the publisher's submitted iOS baseline. Google Play automatic version lookup is not included; existing publisher-supplied Android observations remain supported.

Checks run approximately daily for eligible apps, subject to bounded scheduling. A newer numeric version creates one review notification per app/baseline/store-version combination. Missing baselines, failed lookups and versions that cannot be compared do not establish that an app is stale or unavailable. Failed lookups preserve the last successful observation, which ages under the existing freshness rules.

Review the app context after notification. A binary-only change may require only a publisher-approved baseline update. Blue Jetty never rewrites capabilities or release baselines automatically. Monitoring is independent of publisher authorization and discovery readiness. Current Growth access is rechecked before observation publication and notification delivery.

When the app also has a Google Play listing, the iOS review email adds: “If you also shipped changes on Android, this is a good time to refresh that context too.” This is a reminder to review publisher-known changes, not an observed Android release.

## App alert recipients

In [Email preferences](/account/notifications), the app owner can add up to five additional email addresses per Growth app for iOS release-review and offer-expiry alerts. Eligible pilot access includes this feature. Recipients need not have Blue Jetty accounts; the owner confirms their permission to receive app details. Additional recipients are blind-copied and receive no account or API access. The owner continues receiving the alerts and can remove addresses at any time.

These settings do not redirect sign-in, security, billing or crawler-milestone emails. Saved addresses remain private and inactive after Growth access ends; owners can clear them while on Core. Delivery rechecks current ownership and access. A pending email with a frozen retry payload is suppressed if its recipient list changes, avoiding delivery to removed recipients or a duplicate send under a changed payload. Already accepted emails cannot be recalled.
