@crvouga/mockingbird-service-app-store-connect 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,5 @@
1
+ # Changelog — @crvouga/mockingbird-service-app-store-connect
2
+
3
+ ## 0.1.0 (2026-10-05)
4
+
5
+ Initial release.
package/DISCOVERY.md ADDED
@@ -0,0 +1,55 @@
1
+ # @crvouga/mockingbird-service-app-store-connect discovery
2
+
3
+ This is the installed-package index for coding agents and tooling. All relative links resolve
4
+ inside `node_modules/@crvouga/mockingbird-service-app-store-connect/`; no repository checkout is needed to discover the mock's
5
+ supported surface or documented behavior.
6
+
7
+ ## Capability and behavior sources
8
+
9
+ | Question | Authoritative file | What it contains |
10
+ | --- | --- | --- |
11
+ | Behaviour and integration | [`README.md`](README.md) | Routes, state transitions, auth, webhooks, controls, presets and deliberate omissions. |
12
+ | Exact capabilities | [`SUPPORT.md`](SUPPORT.md) | Supported, unsupported and parity-covered operations or commands, including reasons for gaps. |
13
+ | Wire contract | [`openapi.yaml`](openapi.yaml) | Machine-readable paths, methods, schemas, responses and parity annotations. |
14
+ | Public API | [`dist/index.d.ts`](dist/index.d.ts) | The installed package's exact TypeScript exports and signatures. |
15
+ | Package metadata | [`package.json`](package.json) | Runtime/entry-point claims, vendor links, parity scope/tier and `mockingbird.discovery`. |
16
+
17
+ Read these together: the contract/capability matrix says *what* is available, while the README
18
+ defines stateful behavior, lifecycle rules, test controls, and intentional oracle differences.
19
+ If prose and an executable surface disagree, report a parity mismatch instead of adding a
20
+ consumer-side workaround.
21
+
22
+ ## Parity and oracle
23
+
24
+ - Declared parity surface: **JWT-authenticated apps, users, invitations and TestFlight groups**.
25
+ - Parity tier: **cold** (the repository controls when live checks run).
26
+ - Oracle: **Live vendor API or sandbox**.
27
+ - Repository command: `bun run parity:service -- app-store-connect`.
28
+ - Evidence model: Run from a Mockingbird checkout; credentials come only from .env.local or GitHub Actions secrets. Missing credentials exit 2.
29
+
30
+ The npm package contains evidence summaries and the exact contract, not credentials or the
31
+ repository-only parity harness. Self-parity/property and acceptance tests run in the Mockingbird
32
+ repository; live parity is an additional oracle check, not a substitute for the packaged matrix.
33
+
34
+ ## Runtime introspection
35
+
36
+ - `GET /__admin/health`
37
+ - `GET /__admin`
38
+ - `GET /__admin/state`
39
+ - `GET /__admin/requests`
40
+ - `GET /__admin/metrics`
41
+ - `GET /__admin/faults/presets`
42
+ - `GET /__admin/ui`
43
+
44
+ For HTTP services, use `x-mockingbird-namespace` (or the documented credential/path carrier) so
45
+ parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
46
+ designed for assertions and diagnosis by consuming test suites.
47
+
48
+ ## Report a mismatch or missing capability
49
+
50
+ Follow the [agent reporting contract](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md). Include package version,
51
+ operation/command, a minimal redacted request, actual mock result, expected oracle result or vendor
52
+ documentation, and whether the mismatch appears in the matrix. Never include keys, tokens,
53
+ customer data, prompts, PHI, card data, or unredacted recordings.
54
+
55
+ Service key: `app-store-connect`.
package/README.md ADDED
@@ -0,0 +1,105 @@
1
+ # @crvouga/mockingbird-service-app-store-connect
2
+
3
+ > Familiar calls. Faithful echoes. Part of [Mockingbird](https://github.com/crvouga/mockingbird).
4
+
5
+ WIP App Store Connect mock for JSON:API apps, users, user invitations, beta groups and
6
+ beta testers. ES256 signatures are actually verified; no real Apple account or emails.
7
+
8
+ ## Install
9
+
10
+ ```sh
11
+ bun add -d @crvouga/mockingbird-service-app-store-connect
12
+ ```
13
+
14
+ ## Usage
15
+
16
+ ```ts
17
+ import { createServer } from "@crvouga/mockingbird-service-app-store-connect/server"
18
+ const pair = await crypto.subtle.generateKey(
19
+ { name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"],
20
+ )
21
+ const server = await createServer({
22
+ keys: [{ id: "mock-key", issuer: "mock-issuer", role: "ADMIN",
23
+ publicKey: await crypto.subtle.exportKey("jwk", pair.publicKey) }],
24
+ })
25
+ // Configure the test app's ES256 signer with pair.privateKey and the matching key/issuer ids.
26
+ // Override its Apple origin with server.url. Never use a real Apple private key here.
27
+ await server.close()
28
+ ```
29
+
30
+ `createRuntime().fetch(Request)` supports in-process clients. The CLI starts without trusted
31
+ keys; seed public verification keys through `/__admin/state/keys`, or use server options.
32
+ There is no static bypass bearer token. Private signing material is never needed by the mock;
33
+ options containing a private JWK are rejected. Generate test signing keys at test startup.
34
+
35
+ ### Authentication
36
+
37
+ Team JWTs require ES256, `typ: JWT`, registered `kid`, matching issuer and `appstoreconnect-v1`
38
+ audience, valid `iat`/`exp`, signature verification and a lifetime at most 20 minutes.
39
+ The mock clock determines expiry. `enabled: false` revokes a seeded key. Optional scope
40
+ claims restrict GET paths/query parameters; limit/cursor/sort are ignored for matching as
41
+ documented by Apple. Invalid authentication returns JSON:API 401 before mutation.
42
+
43
+ The scoped write-role policy follows Apple's team/TestFlight guides: ADMIN/ACCOUNT_HOLDER
44
+ may write all supported surfaces; APP_MANAGER may manage beta groups/testers and create
45
+ user invitations. Other seeded roles are denied writes with 403. Read authorization and
46
+ app-specific role restrictions are simplified; see limitations below.
47
+
48
+ ### Routes
49
+
50
+ - GET `/v1/apps`, `/v1/users`, `/v1/userInvitations`, `/v1/betaGroups`, `/v1/betaTesters`.
51
+ - POST `/v1/userInvitations`, `/v1/betaGroups`, `/v1/betaTesters`.
52
+ - GET `/v1/betaGroups/{id}/betaTesters`.
53
+ - POST/DELETE `/v1/betaGroups/{id}/relationships/betaTesters`.
54
+ - POST `/v1/users/{id}/relationships/visibleApps`.
55
+ - DELETE `/v1/users/{id}` and `/v1/userInvitations/{id}`.
56
+
57
+ Lists support limit/cursor, sparse `fields[type]`, name/email filters and the requested
58
+ app filter for groups/testers. `links.next` remains on the configured local origin and keeps
59
+ the public namespace. Relationship writes validate every target before changing anything;
60
+ removing a tester membership does not delete the tester, group or application user.
61
+ Duplicate tester/invitation emails return a 409 JSON:API error and can also be fault-injected.
62
+
63
+ ### Controls
64
+
65
+ Seed `resources` as JSON:API records and `keys` as public verification keys. Seeded group/tester
66
+ and user/visibleApp relationships initialize the durable edge collections. `/__admin/state`
67
+ exposes `resources`, `keys`, `memberships`, `visibleApps` for synthetic fixtures.
68
+ Standard reset, Timeline snapshots/branches, clock, request journal and faults are available.
69
+ Requests use header, `/__admin/ns/<name>/…` path or mapped bearer credential namespaces;
70
+ `adminPrefix` relocates the reserved tree. Journals hold no JWTs or request bodies.
71
+ Presets: `unauthorized`, `forbidden`, `duplicate`, `rate_limited`, `server_error`,
72
+ `connection_drop`; generic faults also support deterministic latency. No webhooks are emitted.
73
+
74
+ ### Verification
75
+
76
+ `bun test` verifies all four reported behaviors through raw fetch, actual signatures using
77
+ independently generated jose ES256 keys, JWT rejection/revocation, scoped writes, seeded edges,
78
+ served HTTP, namespace/reset/fault controls, OpenAPI random walks and deliberate divergence.
79
+ The consumer is a port of the issue's reported surface, not unavailable private app code.
80
+ No official SDK was requested. No live account credentials or writes were used.
81
+ `APP_STORE_CONNECT_TOKEN=… bun run parity` safely probes a single app-list response shape;
82
+ missing credentials exit 2. It is not a full vendor random-walk parity claim.
83
+
84
+ Contract sources: Apple's [official OpenAPI download](https://developer.apple.com/sample-code/app-store-connect/app-store-connect-openapi-specification.zip),
85
+ [JWT guide](https://developer.apple.com/documentation/appstoreconnectapi/generating-tokens-for-api-requests),
86
+ [team guide](https://developer.apple.com/help/app-store-connect/manage-your-team/add-and-edit-users/),
87
+ and [external testers guide](https://developer.apple.com/help/app-store-connect/test-a-beta-version/invite-external-testers).
88
+ Request schemas are retained from the published OpenAPI; response fields are a scoped subset.
89
+
90
+ ## Deliberately not modelled
91
+
92
+ Binary uploads, App Store release, real invitation emails, builds, device installation,
93
+ TestFlight review prerequisites and user acceptance of invitations. Individual-key JWTs and
94
+ long-lived tokens for unrelated Apple APIs are outside this team-key surface. Fine-grained
95
+ read permissions, per-app key access, advanced role assignment restrictions, relationship
96
+ expansion/include and production duplicate diagnostic variants are not guaranteed.
97
+ Admin fixture edits can construct states the live API would forbid; seed coherent records.
98
+
99
+ ## API
100
+
101
+ Root runtime exports: `AppStoreConnectAPI`, `APP_STORE_CONNECT_NAMESPACE`, `DEFAULT_RESOURCES`,
102
+ `createRuntime`, `APP_STORE_CONNECT_PRESETS`, `document`, `operationIds`, `supportedOperationIds`.
103
+ Types: `ApiKey`, `ResourceType`, `Linkage`, `Resource`, `AppStoreConnectAPIOptions`,
104
+ `AppStoreConnectRuntimeOptions`, `AppStoreConnectRuntime`, `OperationId`, `SupportedOperationId`.
105
+ The `/server` entry exports `createServer`, `serveTarget`, `DEFAULT_PORT`.
package/SUPPORT.md ADDED
@@ -0,0 +1,24 @@
1
+ # App Store Connect scoped mock — operation support
2
+
3
+ Generated from `openapi.yaml`; do not edit by hand.
4
+
5
+ - operations in spec: **14**
6
+ - supported by the mock: **14**
7
+ - parity enabled: **14**
8
+
9
+ | operationId | route | mock | parity | notes |
10
+ | --- | --- | --- | --- | --- |
11
+ | `ListApps` | `GET /v1/apps` | ✅ supported | ✅ | |
12
+ | `ListUsers` | `GET /v1/users` | ✅ supported | ✅ | |
13
+ | `ListInvitations` | `GET /v1/userInvitations` | ✅ supported | ✅ | |
14
+ | `CreateInvitation` | `POST /v1/userInvitations` | ✅ supported | ⚠️ unsafe (opt-in) | |
15
+ | `ListGroups` | `GET /v1/betaGroups` | ✅ supported | ✅ | |
16
+ | `CreateGroup` | `POST /v1/betaGroups` | ✅ supported | ⚠️ unsafe (opt-in) | |
17
+ | `ListTesters` | `GET /v1/betaTesters` | ✅ supported | ✅ | |
18
+ | `CreateTester` | `POST /v1/betaTesters` | ✅ supported | ⚠️ unsafe (opt-in) | |
19
+ | `ListGroupTesters` | `GET /v1/betaGroups/{id}/betaTesters` | ✅ supported | ✅ | |
20
+ | `AddGroupTesters` | `POST /v1/betaGroups/{id}/relationships/betaTesters` | ✅ supported | ⚠️ unsafe (opt-in) | |
21
+ | `RemoveGroupTesters` | `DELETE /v1/betaGroups/{id}/relationships/betaTesters` | ✅ supported | ⚠️ unsafe (opt-in) | |
22
+ | `AddVisibleApps` | `POST /v1/users/{id}/relationships/visibleApps` | ✅ supported | ⚠️ unsafe (opt-in) | |
23
+ | `DeleteUser` | `DELETE /v1/users/{id}` | ✅ supported | ⚠️ unsafe (opt-in) | |
24
+ | `DeleteInvitation` | `DELETE /v1/userInvitations/{id}` | ✅ supported | ⚠️ unsafe (opt-in) | |