Skip to content
Last updated

Developer Environment Setup & LLM Starter Kit

Audience: Engineers integrating Jay on Web, iOS, Android, and backend services. Outcome: A ready-to-code environment with curated links (llms.txt, sitemaps), headers/env presets, and copy‑paste prompt recipes for high‑quality results.

1) Purpose

Centralize the links and conventions that AI tools rely on (e.g., llms.txt, sitemaps, OpenAPI) and provide prompt recipes tuned for our stack (TypeScript/Angular, Node, Swift, Kotlin).

These are the first destinations for developers and AI assistants. Include them in your llms.txt.

  • Docs Home: https://docs.jay-metadata.com/
  • Docs Sitemap (HTML): https://docs.jay-metadata.com/sitemap
  • XML Sitemap: https://docs.jay-metadata.com/sitemap.xml
  • OpenAPI – Playout (Latest): https://docs.jay-metadata.com/apis/playout/latest/openapi
  • OpenAPI – Basket v2 (Latest): https://docs.jay-metadata.com/apis/basket/latest/openapi
  • Platform How‑Tos Index: https://docs.jay-metadata.com/platform/how-to
  • Quickstarts Index: https://docs.jay-metadata.com/platform/quickstarts
  • System Overview: https://docs.jay-metadata.com/introduction/system-overview

Minimal llms.txt

# High-priority docs and machine-readable specs for LLMs
ALLOW: https://docs.jay-metadata.com/
PRIORITY: https://docs.jay-metadata.com/platform/quickstarts/streaming-integration
PRIORITY: https://docs.jay-metadata.com/platform/how-to/fetch-data
PRIORITY: https://docs.jay-metadata.com/platform/how-to/use-the-basket
PRIORITY: https://docs.jay-metadata.com/platform/how-to/checkout-stripe
PRIORITY: https://docs.jay-metadata.com/apis/playout/latest/openapi
PRIORITY: https://docs.jay-metadata.com/apis/basket/latest/openapi
SITEMAP: https://docs.jay-metadata.com/sitemap.xml

Keep this list short and canonical.

3) One‑time local setup

  • Extensions: ESLint, Prettier, REST Client or Thunder Client, EditorConfig, GitLens.
  • Settings: format on save, organize imports on save, 2‑space indent.
  • Snippets: add project snippets for common headers and fetch patterns (see below).

REST tools

  • REST Client: store .http files with ready calls (Playout episodes, Basket product details, checkout start/finish).
  • Postman/Insomnia: import the shared collection with environments for Stage/Prod.

CLI helpers

Create scripts/api with simple curl wrappers:

# scripts/api/episodes.sh
curl -sS \
  -H "X-API-Key: $JAY_API_KEY" \
  -H "X-API-Version: ${JAY_PLAYOUT_VER:-2025-09-02}" \
  -H "__Secure-jay_tracking: ${JAY_TRACKING:-local-dev}" \
  "https://live.playout.api.jay-metadata.com/v1/playouts/$1/episodes" | jq .

4) Environment & headers

.env (local)

JAY_API_KEY=xxx
JAY_PLAYOUT_ID=xxx
JAY_PLAYOUT_VER=2025-09-02
JAY_BASKET_VER=2025-09-15
JAY_TRACKING=local-dev

Default headers

X-API-Key: ${JAY_API_KEY}
X-API-Version: ${JAY_PLAYOUT_VER}    # Playout
__Secure-jay_tracking: ${JAY_TRACKING}
Authorization: Bearer <jwt>          # Basket only

Pin versions in CI/CD. Use a cookie or the header for __Secure-jay_tracking per request.

5) Ready‑to‑use prompts

A) System prompt (for any coding assistant)

You are an expert assistant for Jay’s streaming integration stack.
Always prefer the company docs provided via llms.txt and sitemaps.
Constrain answers to the Playout API (content/structure) and Basket API v2 (cart/checkout).
When showing code, use TypeScript fetch examples and include required headers:
- X-API-Key, X-API-Version (pinned), and __Secure-jay_tracking (cookie or header) for Playout
- X-API-Key, X-API-Version, and Authorization: Bearer <jwt> for Basket
Before write access, verify availability via POST /baskets/products/details.
If endpoint shape is uncertain, link to the exact reference page.
Keep answers concise, deterministic, and copy‑pasteable.

B) Retrieval prompt (fetch facts/code from docs)

Using the sources in llms.txt and sitemap.xml, find the latest Basket API v2 reference for
starting and finishing a checkout session. Return:
1) Exact endpoints and required headers
2) Minimal request bodies
3) Expected success responses and common errors
4) Links to the specific sections in the docs

C) Angular service generator (Playout)

Generate an Angular Injectable service `PlayoutService` with methods:
- createTrackingSession()
- listEpisodes(playoutId)
- getEpisode(playoutId, episodeId)
- listGroups(playoutId, episodeId)
- listScenes(playoutId, episodeId)
- listTimelineEvents(playoutId, episodeId)
Use HttpClient. Set default headers (X-API-Key from env token provider, X-API-Version pinned, send
__Secure-jay_tracking cookie when available, else header). Provide strict typings (interfaces) and
handle non-200 with typed errors.

D) Angular interceptor (headers/cookies)

Create an Angular HttpInterceptor that injects the following headers when the URL matches
`*.playout.api.jay-metadata.com` or `*.basket.api.jay-metadata.com`:
- X-API-Key from a ConfigService
- X-API-Version per-domain (playout vs basket)
- For Playout: if cookie `__Secure-jay_tracking` is absent, add header with value from a TrackingService
- For Basket: add Authorization: Bearer <jwt> if available
Make it configurable for SSR vs browser.

E) Basket flow (guest or partner JWT)

Write TypeScript functions to:
1) Create a guest basket → returns { userId, jwt }
2) Check product details via POST /baskets/products/details for a list of basketProductIds
3) Add first available product to the basket
4) Start a checkout session and return Stripe client_secret
5) Finalize the active checkout session
Include error handling for stock changes and a locked basket during checkout.

F) Refactor prompt (production‑ready code)

Refactor the following TypeScript to be production‑ready:
- Strong typings for API responses
- Runtime validation (zod) for external responses
- Centralized error formatting with error codes and actionable messages
- Retries with exponential backoff for 5xx and network errors
- Idempotent POSTs where appropriate
- Unit tests with Vitest for the functions

G) Troubleshooting assistant

Given a failing Basket checkout:
- Inspect for missing Authorization or expired JWT
- Check if the basket is locked due to an active checkout session
- Verify product variants and stock via /baskets/products/details
- Reconcile X-API-Version mismatches between client and server
- Provide specific curl repro commands and link to reference sections

6) Guardrails for AI usage

  • Cite the docs: link back to specific reference sections.
  • No hallucinated endpoints: if uncertain, ask for the canonical reference link.
  • Version discipline: always pin X-API-Version and surface the value used in snippets.
  • Privacy: never log secrets (X-API-Key, JWTs). Use redaction in samples.
  • Test mode: prefer mode: "test" and test tokens for payment flows unless explicitly disabled.

7) Quick checks (for PRs)

  • llms.txt lists the latest quickstarts/how‑tos and OpenAPI links
  • Postman/Insomnia collections exported and linked from docs
  • Env/header examples validated against Prod
  • Sample prompts resolve to correct endpoints and headers
  • Angular interceptor/service compile in a minimal project

8) Changelog

  • 2025‑10‑01: Initial version (setup, curated links, prompts A–G).