docs: desktop D3 (studios, accounts, store-only apps, owner actions, writes) and R&D note on a fastlane importer and a RevenueCat adapter
This commit is contained in:
parent
ba58895d3a
commit
c3454e352d
2 changed files with 197 additions and 2 deletions
|
|
@ -25,8 +25,15 @@ Types of the protocol: `cli/lib/desktop-protocol.ts`; pure portfolio logic: `cli
|
||||||
the sidecar's stdin. Write methods are dry runs unless the call carries a confirm token: HMAC-SHA256 over the
|
the sidecar's stdin. Write methods are dry runs unless the call carries a confirm token: HMAC-SHA256 over the
|
||||||
method, the canonical `{ project, args }` and a 60 s expiry, single use. The host mints one only after the owner
|
method, the canonical `{ project, args }` and a 60 s expiry, single use. The host mints one only after the owner
|
||||||
pressed Apply in a native dialog that shows the summary and the dry run (`write_with_confirm`).
|
pressed Apply in a native dialog that shows the summary and the dry run (`write_with_confirm`).
|
||||||
- No method submits for review, releases, publishes, resumes or completes a rollout. Under `serve`, the CLI's own
|
- No method submits for review, releases an approved version, publishes, cancels a submission, sends a build to
|
||||||
terminal confirmations always answer no.
|
external testers or removes testers. Under `serve`, the CLI's own terminal confirmations answer no, with one
|
||||||
|
exception: the **owner actions** (`owner.play_rollout` share / halt / resume / complete, `owner.ios_phased`
|
||||||
|
on / pause / resume / complete, `owner.reply_send` one approved draft, `owner.testflight_testers` adds the testers
|
||||||
|
of `.storebound/testers.csv`). They are desktop-only (never MCP tools), dry runs from the window like every write,
|
||||||
|
and their real run needs the host token. Only then serve sets `STOREBOUND_OWNER_CONFIRMED` for that one child,
|
||||||
|
which answers the command's question. The native dialog names the action on its button ("Yes: Change the Play
|
||||||
|
staged rollout"). `tests/desktop-d3.test.ts` and `src-tauri/tests/d3_writes.rs` pin the token binding of every
|
||||||
|
write the window offers.
|
||||||
- The webview gets no plugin API. It may call the app commands (each re-checks the window label and the page origin
|
- The webview gets no plugin API. It may call the app commands (each re-checks the window label and the page origin
|
||||||
in Rust) and listen to two events. Strict CSP, no remote content. `src-tauri/tests/security.rs` pins all of it.
|
in Rust) and listen to two events. Strict CSP, no remote content. `src-tauri/tests/security.rs` pins all of it.
|
||||||
- Store keys (Play service account JSON, App Store Connect key id, issuer id and .p8) are picked in native dialogs,
|
- Store keys (Play service account JSON, App Store Connect key id, issuer id and .p8) are picked in native dialogs,
|
||||||
|
|
@ -61,6 +68,84 @@ Types of the protocol: `cli/lib/desktop-protocol.ts`; pure portfolio logic: `cli
|
||||||
(CI) checks keys, empty messages and placeholders. **Theme**: text tokens keep 7:1 contrast in both themes
|
(CI) checks keys, empty messages and placeholders. **Theme**: text tokens keep 7:1 contrast in both themes
|
||||||
(`tests/theme.test.ts`), motion at most 200 ms and off with reduced motion.
|
(`tests/theme.test.ts`), motion at most 200 ms and off with reduced motion.
|
||||||
|
|
||||||
|
## Studios, accounts and store-only apps (D3)
|
||||||
|
|
||||||
|
### Accounts and studios
|
||||||
|
|
||||||
|
- A **studio** is a name, a colour and an optional logo. It groups any number of store accounts:
|
||||||
|
- a Play service account, which can be invited to several Play developer accounts and then sees all their apps;
|
||||||
|
- an App Store Connect team key, one per team.
|
||||||
|
- Keys stay in the keychain. The state file keeps labels and studio ids only.
|
||||||
|
- `storebound apps check` gives each account's health, with the fix in words:
|
||||||
|
- ok;
|
||||||
|
- no-apps;
|
||||||
|
- permission (Play: "invite <service account> in Play Console > Users and permissions with ...");
|
||||||
|
- revoked;
|
||||||
|
- api-disabled.
|
||||||
|
- `storebound apps list` reads the apps an account can see:
|
||||||
|
- App Store Connect: `GET /v1/apps`, the newest version, and an icon from the newest build's `iconAssetToken`,
|
||||||
|
fetched by the CLI and returned as a data URL;
|
||||||
|
- Play: the Reporting API `apps:search`.
|
||||||
|
- Serve exposes both as `apps.list` and `account.check` (kind `account`, one account's key per call, run in an
|
||||||
|
empty temp folder). The host caches app lists under `acct:<id>`.
|
||||||
|
|
||||||
|
### One card per app
|
||||||
|
|
||||||
|
`src/lib/identity.ts` builds one card per app, pure and tested:
|
||||||
|
|
||||||
|
1. A folder takes the store apps its config names. Order: an explicit link, then the App Store app id, then the
|
||||||
|
bundle id or package name. The folder's mapped accounts win.
|
||||||
|
2. The remaining store apps pair iOS + Android, in this order:
|
||||||
|
- manual pairs;
|
||||||
|
- the same id;
|
||||||
|
- a close id (`.ios` / `.android` suffixes, case, punctuation);
|
||||||
|
- the same name.
|
||||||
|
|
||||||
|
Unpairs block automatic pairs.
|
||||||
|
3. What is left is a single-store app.
|
||||||
|
|
||||||
|
Overrides (pairs, unpairs, links, studio moves, the ignore list of apps, folders and whole accounts) live in the
|
||||||
|
host state file (`overrides_set`, every key checked in `workspace.rs`).
|
||||||
|
|
||||||
|
### Store-only apps
|
||||||
|
|
||||||
|
- A store-only app has no folder. It is read through a **store target**:
|
||||||
|
`store:ios:<account>:<app id>:<bundle>;android:<account>:<package>`.
|
||||||
|
- The host checks the target and the account kinds, and passes `virtual: { name, apple, play }`. The sidecar writes
|
||||||
|
a minimal `storebound.config.json` (store ids, placeholder links) into its temp folder.
|
||||||
|
- Only `apple.status`, `play.status`, `health`, `reviews.list`, `apple.testflight_status` and `apple.ppo_status` work
|
||||||
|
this way, and `portfolio.status` takes store-only entries.
|
||||||
|
- "Link a folder" or "Start an app folder here" turn it into a full app.
|
||||||
|
|
||||||
|
### Settings
|
||||||
|
|
||||||
|
- Studios and accounts.
|
||||||
|
- Pairing and the ignore list.
|
||||||
|
- Store reads: on launch, every 15 min to 12 h (off by default), apps at a time 1-8, icons.
|
||||||
|
- Offline cache: size, keep 7 / 30 / 90 / 365 days or always, clear.
|
||||||
|
- Language, theme and motion.
|
||||||
|
- Notifications, after a read, never on the first one: review / release state changes, new 1-2 star reviews, crash
|
||||||
|
or ANR over the Play threshold.
|
||||||
|
- Dependencies and the CLI sidecar.
|
||||||
|
- Privacy, with a button that reveals the data folder.
|
||||||
|
- Shortcuts.
|
||||||
|
- Update channel (placeholder until the updater ships).
|
||||||
|
- Reset: native confirmation, then the keychain entries and every saved state are removed.
|
||||||
|
|
||||||
|
### Writes in the window
|
||||||
|
|
||||||
|
Each write is a dry run, then the native dialog, then the real run, with one progress toast and Cancel:
|
||||||
|
|
||||||
|
- **Listings tab:** Play listing text, App Store version and text, Play graphics, App Store screenshots and
|
||||||
|
previews; local render jobs (screenshots, previews, icons, gallery).
|
||||||
|
- **Catalog tab:** Play products and subscriptions, App Store IAPs and subscriptions, price export. Price import
|
||||||
|
stays a terminal step.
|
||||||
|
- **Releases tab:** rollout and phased release owner actions.
|
||||||
|
- **TestFlight tab:** What to Test, internal groups, testers.
|
||||||
|
- **Reviews tab:** reply editor (`reviews.reply`), approve, send (owner action).
|
||||||
|
|
||||||
|
R&D on a fastlane importer and a RevenueCat adapter: `docs/research/fastlane-revenuecat.md`.
|
||||||
|
|
||||||
## Dependencies screen
|
## Dependencies screen
|
||||||
|
|
||||||
storebound needs no local tool for store work. Screenshots, app previews, icons and captures use:
|
storebound needs no local tool for store work. Screenshots, app previews, icons and captures use:
|
||||||
|
|
|
||||||
110
docs/research/fastlane-revenuecat.md
Normal file
110
docs/research/fastlane-revenuecat.md
Normal file
|
|
@ -0,0 +1,110 @@
|
||||||
|
# R&D: a fastlane importer and a RevenueCat adapter
|
||||||
|
|
||||||
|
Two questions for after desktop D3. Facts come from the official docs linked in each section; the
|
||||||
|
recommendations are ours.
|
||||||
|
|
||||||
|
## 1. `storebound import fastlane`
|
||||||
|
|
||||||
|
**What fastlane keeps on disk**
|
||||||
|
|
||||||
|
- **deliver (App Store)**, under `fastlane/metadata/`
|
||||||
|
([docs.fastlane.tools/actions/deliver](https://docs.fastlane.tools/actions/deliver/)):
|
||||||
|
- One folder per language: `name.txt`, `subtitle.txt`, `description.txt`, `keywords.txt`, `promotional_text.txt`,
|
||||||
|
`release_notes.txt`, `support_url.txt`, `marketing_url.txt`, `privacy_url.txt`.
|
||||||
|
- Non-localized files at the root: `copyright.txt`, `primary_category.txt`, `secondary_category.txt` and the
|
||||||
|
sub-category files.
|
||||||
|
- `review_information/`: `first_name.txt`, `last_name.txt`, `phone_number.txt`, `email_address.txt`,
|
||||||
|
`demo_user.txt`, `demo_password.txt`, `notes.txt`.
|
||||||
|
- A `default/` folder that fills any language without its own files.
|
||||||
|
- Screenshots and app previews in one folder per language. The device comes from the image size or the file name.
|
||||||
|
- **supply (Google Play)**, under `fastlane/metadata/android/<locale>/`
|
||||||
|
([docs.fastlane.tools/actions/supply](https://docs.fastlane.tools/actions/supply/)):
|
||||||
|
- `title.txt`, `short_description.txt`, `full_description.txt`, `video.txt`.
|
||||||
|
- `changelogs/<versionCode>.txt` and `changelogs/default.txt`.
|
||||||
|
- `images/`: `icon`, `featureGraphic`, `promoGraphic`, `tvBanner`, plus `phoneScreenshots/`, `sevenInchScreenshots/`
|
||||||
|
and `tenInchScreenshots/`.
|
||||||
|
- **Appfile / Deliverfile / Fastfile** are Ruby:
|
||||||
|
- `app_identifier`, `apple_id`, `team_id` / `itc_team_id`, `json_key_file`, `package_name`.
|
||||||
|
- Deliverfile options such as `languages`, `submit_for_review`, `automatic_release`, `phased_release`,
|
||||||
|
`price_tier`, `app_rating_config_path`.
|
||||||
|
|
||||||
|
**What an importer would do.** It would only read, it would never run Ruby, and it would write with `--dry` first.
|
||||||
|
|
||||||
|
1. **Store ids.** Parse the simple `key("value")` / `key "value"` lines of `Appfile` and `Deliverfile` with a strict
|
||||||
|
regex. That gives `apple.bundleId`, `play.packageName` and the languages. Ruby logic (conditionals, `ENV[...]`,
|
||||||
|
lanes) is reported as "set by hand", never guessed.
|
||||||
|
2. **Languages.** Join the deliver locales and the supply locales into storebound `languages[]` (`apple`, `play` codes).
|
||||||
|
3. **Listing text.**
|
||||||
|
- Write `store/appstore.md` and `store/listing.md` from the `.txt` files, mapping `default/` into every language
|
||||||
|
that lacks a file.
|
||||||
|
- The newest `changelogs/<versionCode>.txt` becomes `whatsNew`.
|
||||||
|
- Check lengths against the store limits (`storebound check`).
|
||||||
|
4. **Art.** Copy or link the screenshot folders into the renders layout (per language and size), or list them as
|
||||||
|
`shots.frames` when they look like raw captures. The supply icon and feature graphic go to the configured paths.
|
||||||
|
5. **Secrets and personal data.**
|
||||||
|
- `json_key_file` and `review_information/*` (contact, demo user and password) go to
|
||||||
|
`.storebound/credentials.json`, which is gitignored, and never to the config (AGENTS.md rules 4 and 9).
|
||||||
|
- The importer prints that it moved them, masked.
|
||||||
|
6. **Not imported, with a note:**
|
||||||
|
- Submission and release flags (`submit_for_review`, `automatic_release`). storebound never submits.
|
||||||
|
- `price_tier`. Prices live in the products / CSV flow.
|
||||||
|
- The age rating config (answered with the owner in `store-declarations`).
|
||||||
|
- Fastfile lanes.
|
||||||
|
|
||||||
|
**Worth it? Yes.** fastlane is the most common existing setup, and its metadata folder maps almost one to one onto
|
||||||
|
storebound's listing files. A read-only importer gives a migration path that keeps the store text, the screenshots
|
||||||
|
and the credentials layout in a few seconds, and a dry run shows exactly what lands where.
|
||||||
|
|
||||||
|
**Effort:** about 2 to 3 days with tests on fixture folders: an Appfile / Deliverfile line parser, the two metadata
|
||||||
|
walkers, a dry-run report, and the `.storebound/` hand-off. Ship it as `storebound import fastlane [--dir fastlane]
|
||||||
|
[--dry]`, then as an "Import from fastlane" choice in the desktop first-run guide.
|
||||||
|
|
||||||
|
## 2. A RevenueCat adapter
|
||||||
|
|
||||||
|
**What the API offers.** RevenueCat REST API v2 lives at `https://api.revenuecat.com/v2`. It uses Bearer v2 secret
|
||||||
|
keys with per-endpoint permissions, set in the project settings ([revenuecat.com/docs/api-v2](https://www.revenuecat.com/docs/api-v2)).
|
||||||
|
It covers:
|
||||||
|
|
||||||
|
- Apps.
|
||||||
|
- Products: `/projects/{project_id}/products`.
|
||||||
|
- Entitlements, with `.../entitlements/{entitlement_id}/actions/attach_products`.
|
||||||
|
- Offerings and Packages.
|
||||||
|
|
||||||
|
So the RevenueCat catalog can be created and kept in sync by API.
|
||||||
|
|
||||||
|
**What storebound already replaces.** The store-side catalog: one product and subscription list in the config,
|
||||||
|
created and priced on both stores (`play products / subscriptions`, `apple iap / subscriptions`, the regional price
|
||||||
|
CSV), with cross-store parity (`catalog diff`). Teams that use RevenueCat only as a way to "set up the products"
|
||||||
|
don't need it for that.
|
||||||
|
|
||||||
|
**What storebound cannot replace.**
|
||||||
|
|
||||||
|
- Runtime receipt and purchase-token validation.
|
||||||
|
- Entitlement state per user, server notifications (App Store Server Notifications, Play RTDN).
|
||||||
|
- Renewals, grace periods, refunds, customer history, paywall experiments and charts.
|
||||||
|
- The client SDKs.
|
||||||
|
|
||||||
|
All of that runs on a server, against live users. It is outside a release tool, and storebound should not try.
|
||||||
|
|
||||||
|
**What an optional adapter could do:** `storebound revenuecat sync [--dry]`.
|
||||||
|
|
||||||
|
- Key: `REVENUECAT_API_KEY` (v2 secret) and project id, from the environment or `.storebound/` only.
|
||||||
|
- Source of truth: the storebound catalog. For every config product or subscription id and each store:
|
||||||
|
1. Create the RevenueCat product (store identifier, app id, type).
|
||||||
|
2. Create the entitlements named in a new optional config field (`products[].entitlements: ['pro']`) and attach
|
||||||
|
the products.
|
||||||
|
3. Optionally create one default offering whose packages map to the subscriptions (`$rc_monthly` / `$rc_annual`
|
||||||
|
by period).
|
||||||
|
- Idempotent: match by store identifier. A dry-run diff comes first, as with every storebound write. Nothing is
|
||||||
|
deleted.
|
||||||
|
- Read-only parity: show "missing in RevenueCat" in `catalog diff` and in the desktop Catalog tab.
|
||||||
|
|
||||||
|
**Recommendation.** Build the fastlane importer first: it is the migration path and the bigger win.
|
||||||
|
|
||||||
|
Make RevenueCat a small, optional adapter later, scoped to catalog sync (products, entitlements, a default offering)
|
||||||
|
plus parity in `catalog diff`. Market it as "keep RevenueCat in step with the stores", not as a replacement:
|
||||||
|
|
||||||
|
- storebound owns the store-side catalog and the release.
|
||||||
|
- RevenueCat (or the app's own server) owns runtime entitlements.
|
||||||
|
|
||||||
|
Do not add webhooks, customers or any runtime data, so storebound stays a local tool with no server and no user data.
|
||||||
Loading…
Add table
Add a link
Reference in a new issue