How paypaldev/video-bytemonkio-paypal-tutorial works
This repository is a PayPal sandbox integration and narrated failure-mode demo. The main runtime flow is buyer checkout through the local server and PayPal Orders API, with later webhook deliveries verified, deduplicated, and applied to application-owned order or subscription state. Separate runnable scenarios demonstrate idempotency, error handling, subscription billing, Venmo eligibility, and scoped agent access. The graph uses the README and SOURCE INDEX references; unsampled server wiring is represented only where the index names the relationship.
Main entry points: server.ts HTTP server · client.ts HTTP client · _common.ts Scenario helpers · handle-event.ts Event handler
Components 25
Entry points
- HTTP server
src/server.ts - Checkout page
public/index.html - Environment config
src/config.ts - Console narration
src/log.ts
PayPal integration
- Orders API
src/paypal/orders.ts - Subscriptions API
src/paypal/subscriptions.ts - Webhook verification
src/paypal/webhooks.ts - HTTP client
src/paypal/client.ts - Token authentication
src/paypal/auth.ts - Error classification
src/paypal/errors.ts
Application state
- Event handler
src/domain/handle-event.ts - Order state
src/domain/order-state.ts - Subscription state
src/domain/subscription-state.ts
Local persistence
- Webhook event log
src/store/events.ts - Idempotency ledger
src/store/ledger.ts - JSON file store
src/store/json-store.ts
Runnable demonstrations
- Checkout and retries
scenarios/01-checkout-happy-path.ts - Webhook replay demo
scenarios/03-webhook-replay.ts - Subscription lifecycle
scenarios/05-subscription-lifecycle.ts - Error demonstrations
scenarios/04-errors-three-ways.ts - Agent toolkit
scenarios/07-agent-toolkit.ts - Venmo eligibility
scenarios/06-venmo-eligibility.ts - Scenario helpers
scenarios/_common.ts
Other components
- Buyer browser
- PayPal sandbox
Connections 39
- Buyer browser → Checkout page: opens
README.md - Checkout page → HTTP server: submits checkout
README.md - HTTP server → Orders API: creates and captures
src/server.ts - HTTP server → Webhook verification: verifies deliveries
src/server.ts - PayPal sandbox → HTTP server: delivers webhooks
README.md - HTTP server → Event handler: handles verified events
src/server.ts - Event handler → Webhook event log: records deliveries
src/domain/handle-event.ts - Event handler → Order state: applies order events
src/domain/handle-event.ts - Event handler → Subscription state: applies billing events
src/domain/handle-event.ts - HTTP server → Order state: reads order state
src/server.ts - HTTP server → Idempotency ledger: uses capture ledger
src/server.ts - HTTP server → Subscription state: reads subscription state
src/server.ts - Orders API → HTTP client: sends API calls
src/paypal/orders.ts - Subscriptions API → HTTP client: sends API calls
src/paypal/subscriptions.ts - Webhook verification → HTTP client: checks and resends
src/paypal/webhooks.ts - HTTP client → Token authentication: gets access token
src/paypal/client.ts - HTTP client → Error classification: classifies failures
src/paypal/client.ts - HTTP client → PayPal sandbox: calls REST API
src/paypal/client.ts - Environment config → HTTP client: configures endpoint
src/paypal/client.ts - Environment config → Webhook verification: provides webhook ID
src/paypal/webhooks.ts - Order state → JSON file store: persists orders
src/domain/order-state.ts - Subscription state → JSON file store: persists subscriptions
src/domain/subscription-state.ts - Webhook event log → JSON file store: persists events
src/store/events.ts - Idempotency ledger → JSON file store: persists attempts
src/store/ledger.ts - Checkout and retries → Orders API: runs checkout
scenarios/01-checkout-happy-path.ts - Checkout and retries → Idempotency ledger: records retries
scenarios/01-checkout-happy-path.ts - Webhook replay demo → Webhook verification: replays events
scenarios/03-webhook-replay.ts - Webhook replay demo → Event handler: exercises handling
scenarios/03-webhook-replay.ts - Subscription lifecycle → Subscriptions API: runs billing lifecycle
scenarios/05-subscription-lifecycle.ts - Subscription lifecycle → Subscription state: shows access state
scenarios/05-subscription-lifecycle.ts - Error demonstrations → Error classification: demonstrates outcomes
scenarios/04-errors-three-ways.ts - Agent toolkit → Orders API: creates orders
scenarios/07-agent-toolkit.ts - Agent toolkit → Idempotency ledger: audits attempts
scenarios/07-agent-toolkit.ts - Venmo eligibility → Environment config: checks environment
scenarios/06-venmo-eligibility.ts - Scenario helpers → Orders API: polls order status
scenarios/_common.ts - Scenario helpers → Token authentication: describes token
scenarios/_common.ts - Scenario helpers → Environment config: checks sandbox mode
scenarios/_common.ts - Scenario helpers → Error classification: formats failures
scenarios/_common.ts - Scenario helpers → Console narration: prints narration
scenarios/_common.ts