From 0f9d0121a241635c6169fb7decb238b1e92314c7 Mon Sep 17 00:00:00 2001 From: Facundo Menzella Date: Tue, 24 Feb 2026 12:10:23 +0100 Subject: [PATCH] Add AGENTS.md for AI coding agent guidance Provides development guidelines for AI agents working with this repository, including: - Project overview and TypeScript/Svelte architecture - Common development commands (pnpm) - Public API stability guidelines - Payment gateway integration patterns - PR labeling conventions - Code guardrails Co-Authored-By: Claude Opus 4.5 --- AGENTS.md | 173 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..e2b7388a3 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,173 @@ +# purchases-js — Development Guidelines + +This file provides guidance to AI coding agents when working with code in this repository. + +## Project Overview + +RevenueCat's official JavaScript/TypeScript SDK for web-based in-app billing. Supports Stripe and Paddle payment gateways with native paywall UI components built with Svelte. + +**Related repositories:** +- **UI Components**: https://github.com/RevenueCat/purchases-ui-js — Shared UI components +- **Hybrid Common**: https://github.com/RevenueCat/purchases-hybrid-common — Shared types and mappings + +When implementing features or debugging, check these repos for reference and patterns. + +## Important: Public API Stability + +**Do NOT introduce breaking changes to the public API.** The SDK is used by many production web apps. + +**Safe changes:** +- Adding new optional parameters to existing methods +- Adding new classes, methods, or properties +- Bug fixes that don't change method signatures +- Internal implementation changes + +**Requires explicit approval:** +- Removing or renaming public classes/methods/properties +- Changing method signatures (parameter types, required params) +- Changing return types +- Modifying behavior in ways that break existing integrations + +The `api-report/` directory tracks the public API surface. Run `pnpm run extract-api` to validate API changes. + +## Code Structure + +``` +purchases-js/ +├── src/ +│ ├── main.ts # Main entry point - Purchases class +│ ├── entities/ # Type definitions & data models +│ ├── helpers/ # Utility functions +│ ├── networking/ # API communication +│ ├── ui/ # Svelte UI components +│ ├── behavioural-events/ # Analytics & event tracking +│ ├── stripe/ # Stripe payment integration +│ ├── paddle/ # Paddle payment integration +│ └── tests/ # Test suite +├── dist/ # Build output (UMD + ESM + CSS) +├── examples/webbilling-demo/ # Demo application +├── api-report/ # API documentation +├── .storybook/ # Storybook configuration +└── fastlane/ # Release automation +``` + +## Common Development Commands + +```bash +# Install dependencies +pnpm install + +# Build +pnpm run build # TypeScript + Vite build (UMD + ES) +pnpm run build:dev # Development build +pnpm run build:dev-watch # Watch mode development +pnpm run watch # Vite watch mode + +# Testing +pnpm run test # Run tests with Vitest +pnpm run test:watch # Watch mode testing +pnpm run test:typecheck # TypeScript type checking +pnpm run typecheck # Full typecheck without emit + +# Code Quality +pnpm run lint # Prettier check +pnpm run format # Prettier formatting +pnpm run svelte-check # Svelte template checking + +# UI & Documentation +pnpm run storybook # Run Storybook dev server (port 6006) +pnpm run build-storybook # Build static Storybook +pnpm run extract-api # Generate API documentation + +# Package for local testing +pnpm run pack-build # Build + npm pack +``` + +## Project Architecture + +### Main Class: `Purchases` (src/main.ts) +- **Singleton Pattern**: `Purchases.sharedInstance` accessible via `getSharedInstance()` +- **Initialization**: `Purchases.configure(config)` — must be called first +- **Key Methods**: + - `getOfferings()` — Fetch products & offerings + - `purchasePackage()` — Process purchase + - `getCustomerInfo()` — Get user subscription data + - `logIn()` / `logOut()` — User authentication + - `presentPaywall()` — Display native paywall UI + +### Payment Gateways +- **Stripe** (`stripe/`) — Primary payment provider +- **Paddle** (`paddle/`) — Secondary payment provider +- **Simulated Store** — For testing + +### UI Components +- Built with **Svelte 5** using runes syntax +- Components in `src/ui/` follow atomic design (atoms → molecules → organisms) +- **Storybook** documentation at port 6006 + +### Testing +- **Framework**: Vitest with jsdom environment +- **Component Testing**: @testing-library/svelte +- **API Mocking**: Mock Service Worker (MSW) + +## Constraints / Support Policy + +| Requirement | Version | +|-------------|---------| +| Node.js | ^22.18 or ^24.11 | +| pnpm | 10.23.0 | +| TypeScript | 5.7.2 | + +## Testing + +```bash +# Unit tests +pnpm run test + +# Type checking +pnpm run typecheck + +# Svelte validation +pnpm run svelte-check + +# API surface validation +pnpm run extract-api +``` + +## Development Workflow + +1. Install dependencies: `pnpm install` +2. Start dev server: `pnpm run build:dev-watch` +3. Run Storybook for UI development: `pnpm run storybook` +4. Make changes +5. Run tests: `pnpm run test` +6. Format code: `pnpm run format` +7. Validate types: `pnpm run typecheck` + +## Pull Request Labels + +When creating a pull request, **always add one of these labels** to categorize the change: + +| Label | When to Use | +|-------|-------------| +| `pr:feat` | New user-facing features or enhancements | +| `pr:fix` | Bug fixes | +| `pr:other` | Internal changes, refactors, CI, docs, or anything that shouldn't trigger a release | + +## When the Task is Ambiguous + +1. Search for similar existing implementation in this repo first +2. Check purchases-ui-js for UI component patterns +3. If there's a pattern, follow it exactly +4. If not, propose options with tradeoffs and pick the safest default + +## Guardrails + +- **Don't invent APIs or file paths** — verify they exist before referencing them +- **Don't remove code you don't understand** — ask for context first +- **Don't make large refactors** unless explicitly requested +- **Keep diffs minimal** — only touch what's necessary, preserve existing formatting +- **Don't break the public API** — run `pnpm run extract-api` to validate +- **Follow Svelte 5 patterns** — use runes syntax (`$props()`, `$derived`) +- **Run format and lint** before committing +- **Never commit API keys or secrets** — do not stage or commit credentials or sensitive data