Skip to content

Packaging & Sandbox Guidelines

Marketplace submissions must package cleanly and respect the managed sandbox so customers can review, install, and run extensions safely. Use this checklist before requesting certification.

Packaging Requirements

  • Deterministic builds – kiket extensions package (or SDK-specific build scripts) must generate reproducible artifacts. Commit lockfiles and pin container/base images.
  • Manifest accuracy – manifest.yml needs explicit version numbers, semantic compatibility, and populated billing metadata (trial length, usage dimensions, plan mapping).
  • Source bundle – Include the full source (or a reproducible build recipe) plus compiled assets. Artifacts must be under 50 MB when compressed.
  • Health endpoint – /healthz or /health must respond with JSON containing status, version, and timestamp. CLIs hit this endpoint during install validation.
  • Replay fixtures – Provide at least one payload under replay/ so reviewers can run kiket extensions replay without handcrafting JSON.

Sandbox Expectations

  • Network egress – Calls must originate from the extension service; never ask the platform to reach into arbitrary hosts on your behalf. Declare required domains in the manifest to aid firewall reviews.
  • Secrets – Fetch secrets through the Extension Secret Store. Do not ship secrets in code or request global credentials.
  • Data locality – Keep customer data within the deployment region declared in the manifest. If you proxy to other regions, document it in compliance.notes.
  • Runtime timeouts – Webhook handlers should respond within 10 s (default) or the custom timeout declared in delivery.handshake. Always stream JSON errors instead of HTML.
  • Logging – Mask tokens/PII before logging. Cloud logs are surfaced to admins during reviews.

Billing Alignment

  • Plan targeting – Use the manifest billing.packages block to describe how usage maps to Starter/Professional/Enterprise plans. Explain value props in the marketplace listing.
  • Usage meters – Emit telemetry via context.endpoints.log_event or the SDK helpers so admins can trace consumption.
  • Revenue share – Specify the baseline percentage (70/30 default) and any negotiated tiers in the listing metadata so invoicing aligns with finance expectations.

Submission Tips

  1. Run kiket extensions lint --all to catch manifest, schema, and packaging issues.
  2. Execute kiket extensions test and kiket extensions replay to prove runtime behavior.
  3. Document deployment/runbook steps in README.md inside the artifact bundle.
  4. Attach sandbox screenshots or diagrams if you rely on external review boards.

Following these guidelines keeps reviews short and ensures customers understand how your extension behaves inside their workspace.