Skip to content

agent-integration.md

Latest commit

 

History

History
44 lines (31 loc) · 2.23 KB

agent-integration.md

File metadata and controls

44 lines (31 loc) · 2.23 KB
Raw

Agent integration guide

This repository is structured for coding agents and CI systems as well as humans.

Inputs an agent must obtain

  • ZipQuantum API base URL, normally https://a.zq.tn.
  • Verified link hostname.
  • iOS Team ID and Bundle ID, Android application ID and SHA-256 certificate fingerprint, or both for a cross-platform React Native app.
  • A non-production test link from the DDL Test Lab.

Never infer these values from branding or repository names. Read them from the ZipQuantum dashboard or explicit environment variables.

Safe execution order

  1. Validate local configuration.
  2. Verify apple-app-site-association or assetlinks.json over HTTPS.
  3. Build the native app.
  4. Run direct-link tests with the app installed.
  5. Run deferred tests only with a disposable test link/token.
  6. Confirm the aggregate funnel reaches route_opened.

For React Native, treat react-native/ios and react-native/android as required platform code, not optional JavaScript fallbacks. Do not replace UIPasteControl with a clipboard module.

For Flutter, treat flutter/ios and flutter/android the same way. The MethodChannel surface is intentionally narrow and transports only a user-approved iOS handoff or raw Play Install Referrer value.

For Tauri, register tauri-plugin-single-instance before tauri-plugin-deep-link. Direct cold-start and warm URLs must enter the same allowlisted parser. The local deferred-link plugin is one-shot: Android reads Play Install Referrer once, while iOS presents a visible UIPasteControl and waits for the user's action. Never add a silent clipboard fallback. Do not add a desktop route_ack unless a distinct server-side desktop trust contract exists.

Machine behavior

  • Commands are non-interactive.
  • JSON contracts live in contracts/.
  • Validation uses stable prefixes: ZQ_OK, ZQ_WARN, and ZQ_ERROR.
  • Exit 0 means all static checks passed; any ZQ_ERROR produces non-zero exit.
  • Logs must redact token, receipt, authorization headers, and signing secrets.

Error handling

Fail closed on an invalid scheme, host, app identifier, HTTP status, expired receipt, or malformed response. Report the failing invariant and remediation; never fall back to fingerprinting or silent clipboard access.