Testing & Release

Test the contract without real provider credentials

npm run test:integrations

Inject or mock the provider client. Automated tests must not call a live provider, depend on developer credentials, or require network access. Add a focusedvalidateAdapter(adapter) contract test beside provider mapping and error tests, then keep the full suite as the release gate.

Run the provider-scoped index migration before traffic

node migrations/database/migrate-ticket-integration-indexes.js

node migrations/database/migrate-ticket-integration-indexes.js --apply

Upstream IDs are unique only inside their Provider and owner scope. The migration replaces legacy global uniqueness with Provider-scoped account, group, event, and fulfillment identities. It also canonicalizes one accepted Provider row, backfills connection generations and creates scheduler, rate-limit TTL, and commission indexes.

• Dry-run blocks on duplicate provider names, duplicate normalized keys, and manifest key/name/alias disagreements.
• Malformed Provider config, broken non-null group references, or ambiguous owner/account matches require manual repair; the migration does not guess or auto-merge rows.
• Production runs with autoIndex disabled, so application startup cannot replace this pre-traffic gate.
• Use a database backup and normal change window. The deployment workflow must stop before versioning, artifact build, or Lambda traffic if apply mode fails.

node migrations/database/migrate-integration-app-pricing.js

node migrations/database/migrate-integration-app-pricing.js --apply

The second migration fills missing public app metadata andProvider.config.checkout_fee for the canonical Bookt, Posh, and Eventbrite rows, snapshots missing raw_data.checkout_fee_policy on imported resources, and defaults a missingProviderAccount.settings.integration_fee_payer. It preserves existing reviewed copy, protected Provider config, explicit payer choices, and historical snapshots. Invalid or ambiguous state blocks apply instead of being overwritten.

Configure the real Provider row before enabling inventory

1. 1

   Keep the adapter disabled

   Ship with catalog.enabledByDefault: false and leave scheduled sync off.

2. 2

   Bind the catalog row

   Deploy the reviewed adapter so catalog initialization resolves or creates the environment's Provider row by key/name and binds its actual Mongo ID.

3. 3

   Verify identity

   Confirm the row's key, canonical name, environment-owned _id, and config.integration_key describe the same integration.

4. 4

   Add protected application settings

   Place provider-level application credentials and operational settings in Provider.config through the restricted operator process, never through a client request.

5. 5

   Review checkout pricing

   Add a versioned Provider.config.checkout_fee policy with a canonical currency, ordered components, allowed/default payers, public source, verification date, and summary before an adapter declaring ticket inventory imports new classes.

6. 6

   Configure auth throttling

   Set a stable independently generated INTEGRATION_AUTH_RATE_LIMIT_HASH_SECRET and apply the migration-created TTL index before exposing login methods.

Exercise the complete live chain in staging

1. 1

   Connect an internal owner

   Use an approved provider test account and the same authentication method the production manifest will expose.

2. 2

   Compare imports

   Verify every organization/group, event page, ticket class, nominal price, currency, availability, pagination count, and partial error against the provider.

3. 3

   Test Eventbrite surfaces independently

   For Eventbrite, run organizer login, official profile/organization/event reads, private ticket inventory, and private guest-list issuance. Prove the connected-user token on each surface.

4. 4

   Place controlled payer orders

   Use a safe event and buyer with Purchaser pays and Merchant covers. Verify the server quote, Stripe charge/application fee, Purchase.checkout_pricing snapshot, one upstream issuance, and provider reference.

5. 5

   Exercise full refunds

   Verify purchaser-paid fees retain the snapshotted fee while refunding the base, merchant-paid fees refund the full buyer charge and application fee, and both reverse the transfer without changing the original snapshot.

6. 6

   Repeat the same attempt

   Dispatch fulfillment again with the identical test idempotency key and confirm that exactly one provider order or guest exists.

7. 7

   Exercise recovery

   Simulate a retryable failure and an ambiguous response. Verify bounded retry, reconciliation_required behavior, withheld confirmation, and audited manual resolution.

Enable catalog access before scheduled work

1. 1

   Enable only in staging or a pilot environment

   Turn on the Provider catalog in a staging or otherwise isolated pilot environment first while scheduled sync remains disabled. The current catalog does not provide a per-account enablement gate.

2. 2

   Observe manual use

   Monitor authentication failures, partial-sync counts, item errors, provider latency, rate limits, reconnect state, and fulfillment attention rows.

3. 3

   Enable the shared schedule

   Declare and enable scheduled sync only after connect-time and manual sync are stable. Confirm queue leases, fairness indexes, abort propagation, batch limits, and Lambda safety windows.

4. 4

   Promote one environment at a time

   After the isolated pilot is stable, enable the Provider catalog in the next environment while comparing Diem counts and upstream records. Keep an assigned owner for reconciliation and credential rotation.

Rollback availability, not data safety

• Disable catalog access and scheduled work first; prevent new connections and imports while preserving durable records for investigation.
• Do not restore legacy global unique indexes during an application rollback. They encode the cross-provider collision defect the migration removes.
• Do not delete imported events, fulfillment rows, Provider accounts, or Provider configuration to make a dashboard look clean.
• Reconcile every settled payment and ambiguous provider issuance before resuming traffic; use the same stable idempotency key and provider reference.
• Rotate compromised provider credentials at the upstream service and in the protected Provider row, then require reconnect where necessary.
• Document the affected provider, accounts, resources, time window, partial counts, buyer orders, and audited manual corrections before re-enabling.