Skill payments demo (placeholder)

This repository is a minimal template for gating a skill behind a one-time Stripe payment. The “premium” behavior is intentionally a placeholder: after payment verification, your product code would run here.

What ships in this demo

• scripts/check_payment.py — Stripe Checkout Session lookup by customer email, minimum amount check (MIN_AMOUNT_CENTS in code), optional Payment Link URL from the environment, and a local receipt cache on disk (see below).
• requirements.txt — pins stripe>=7.0.0 (Stripe’s Python SDK). Install before importing check_payment.
• This SKILL.md — agent instructions: always verify payment first, then proceed to placeholder premium steps.

Environment variables (sensitive — host / deployment only)

These are read by scripts/check_payment.py via os.environ. Do not ask end users for STRIPE_SECRET_KEY. Configure them in the environment where the agent or skill host runs (or a local .env for development — see .env.example; never commit secrets).

Dependencies and install

1. Use Python 3 with pip available.
2. From this skill’s repository root, install the declared dependency:

pip install -r requirements.txt

That installs stripe>=7.0.0. Calls to Stripe’s API require outbound network access from the runtime.

Local disk: receipt cache

After a successful complete_payment_verification, the script writes a small JSON file (with a checksum) to:

~/.skill-payment-demo-receipt

On later runs, check_payment_status() reads that file to skip re-querying Stripe when the receipt is still valid. Users and publishers should treat this path as agent-local state (not shared across machines). Production skills may replace this with different storage or user binding.

Step 1 — Payment gate (mandatory first)

The agent must run the payment check before any premium behavior.

1a. Import and check existing receipt

import sys
sys.path.insert(0, "<SKILL_DIR>/scripts")
from check_payment import (
    check_payment_status,
    get_payment_link,
    complete_payment_verification,
)

if check_payment_status():
    print("Payment verified — premium section allowed.")
else:
    print("Payment required for premium features.")

Replace <SKILL_DIR> with this skill’s directory on disk.

If check_payment_status() is True, skip to Step 2.

1b. Not paid — show Payment Link

link = get_payment_link()
print("Complete the one-time payment to unlock premium features:")
print(f"  → {link}")
print()
print("After paying, reply with the email address you used at checkout.")

Stop and wait for the user’s email.

1c. Verify by email

email = "<user's email>"
if complete_payment_verification(email):
    print("Payment verified.")
else:
    print("No matching completed payment for that email. Check the address and try again.")
    # Do not run premium logic

If verification fails, do not proceed. If STRIPE_SECRET_KEY is missing or misconfigured, treat it as a server-side error (do not ask the user for the secret).

Step 2 — Placeholder premium behavior

After payment is verified (receipt or successful complete_payment_verification), respond with a short confirmation, for example:

Premium area unlocked (demo). Replace this section in SKILL.md with your real skill: API calls, tools, or scripts.

There is no streaming or external data feed in this repo by design.

Error handling

• Not paid / verification failed: Show the link again; do not run premium logic.
• Stripe errors: Say verification is temporarily unavailable; retry later.
• CLI test: python scripts/check_payment.py (requires STRIPE_SECRET_KEY; optional STRIPE_PAYMENT_LINK_URL).

Security notes for publishers

• Never commit STRIPE_SECRET_KEY or live customer data; use environment variables and a .gitignore for local secrets.
• Adjust MIN_AMOUNT_CENTS in check_payment.py to match your Payment Link price.
• The receipt cache path and behavior are documented under Local disk: receipt cache above.