docs(subscription-example): align buyer/seller docs with scenario-based flow

Author: ariessa

examples/acp-base/subscription/README.md

@@ -6,16 +6,21 @@ This example demonstrates how to test subscription-backed jobs with ACP v2 using
 
 The flow covers:
 
-- Buyer initiates a job with subscription metadata.
-- Seller checks the account subscription status.
+- Assumes the selected agent has:
+   - subscription offering at `jobOfferings[0]`
+   - fixed-price offering at `jobOfferings[1]`
+- Buyer runs one of two scenarios:
+   - Scenario 1: subscription offering
+   - Scenario 2: fixed-price offering
+- Seller handles incoming jobs by price type.
+- For subscription jobs, seller checks account subscription status.
 - If no valid subscription exists, seller requests subscription payment.
-- Buyer pays the subscription and continues the normal job flow.
-- Subsequent jobs reuse the active subscription account (no additional subscription payment).
+- If subscription is active, seller proceeds without requesting subscription payment.
 
 ## Files
 
-- buyer.ts: Initiates the subscription job and handles subscription payment.
-- seller.ts: Validates subscription status and requests subscription payment when needed.
+- buyer.ts: Runs scenario-based job initiation and handles subscription/fixed-price memo flows.
+- seller.ts: Handles fixed-price and subscription paths, including subscription payment requirements.
 - env.ts: Loads environment variables from .env.
 
 ## Setup
@@ -32,9 +37,9 @@ The flow covers:
 2. Install dependencies (from repo root):
    - npm install
 
-3. Update buyer.ts placeholders:
-   - Replace <your-filter-agent-keyword>
-   - Replace <your-schema-key> and <your-schema-value>
+3. Ensure selected agent has at least:
+   - One subscription offering at index `jobOfferings[0]`
+   - One fixed-price offering at index `jobOfferings[1]`
 
 ## Run
 
@@ -44,23 +49,27 @@ The flow covers:
 
 2. Start the buyer in another terminal:
    - cd examples/acp-base/subscription
-   - npx ts-node buyer.ts
+   - npx ts-node buyer.ts --scenario 1 # Subscription offering
+   - npx ts-node buyer.ts --scenario 2 # Fixed-price offering
 
 ## Expected Flow
 
-- Job 1:
-  - Buyer creates a job with subscription metadata (sub_premium).
-  - Seller checks subscription validity and requests payment if expired/missing.
-  - Buyer pays the subscription and then pays the job requirement.
-  - Seller delivers, job completes.
+- Scenario 1 (Subscription offering):
+   - Buyer initiates a subscription job with tier metadata (for example `sub_premium`).
+   - Seller checks subscription validity.
+   - If missing/expired, seller creates `PAYABLE_REQUEST_SUBSCRIPTION`.
+   - Buyer calls `paySubscription(...)`.
+   - Seller moves forward and eventually delivers in `TRANSACTION` phase.
+   - If you run scenario 1 again while subscription is active, seller skips subscription payment and sends a plain requirement.
 
-- Job 2:
-  - Buyer creates a second job with the same metadata.
-  - Subscription account is reused, no subscription payment requested.
-  - Normal job flow continues.
+- Scenario 2 (Fixed-price offering):
+   - Buyer initiates a non-subscription job.
+   - Seller accepts and creates `PAYABLE_REQUEST`.
+   - Buyer pays with `payAndAcceptRequirement(...)`.
+   - Seller delivers in `TRANSACTION` phase.
 
 ## Notes
 
 - Both agents must be registered and whitelisted on ACP.
-- The seller config uses a local price table for subscription tiers.
+- Subscription tier name in buyer defaults to `sub_premium`; adjust to match seller offering config.
 - If the buyer does not see the seller, make sure the seller has at least one job offering and is searchable by the buyer's keyword.

examples/acp-base/subscription/buyer.ts

@@ -7,15 +7,9 @@
  *
  * Default: scenario 1
  *
- * Scenarios:
- *   1. Subscription Offering
- *      - Seller creates PAYABLE_REQUEST_SUBSCRIPTION memo
- *      - Buyer pays subscription; job proceeds to delivery
- *
- *   2. Non-Subscription Offering (Fixed-Price)
- *      - Uses a non-subscription offering (jobOfferings[1])
- *      - Seller accepts and creates a payable requirement
- *      - Buyer pays and advances to delivery
+ * Assumption:
+ * - chosenAgent.jobOfferings[0] is a subscription offering
+ * - chosenAgent.jobOfferings[1] is a non-subscription (fixed-price) offering
  */
 import AcpClient, {
   AcpContractClientV2,
@@ -39,7 +33,8 @@ const SUBSCRIPTION_TIER = "sub_premium";
 
 // Parse --scenario N from argv
 const scenarioArg = process.argv.indexOf("--scenario");
-const SCENARIO = scenarioArg !== -1 ? parseInt(process.argv[scenarioArg + 1], 10) : 1;
+const SCENARIO =
+  scenarioArg !== -1 ? parseInt(process.argv[scenarioArg + 1], 10) : 1;
 
 async function buyer() {
   console.log(`=== Subscription Example - Buyer (Scenario ${SCENARIO}) ===\n`);
@@ -66,37 +61,55 @@ async function buyer() {
         console.log(
           `Buyer: Job ${job.id} — Subscription payment requested: ${memoToSign.content}`,
         );
-        console.log(`Buyer: Job ${job.id} — Amount: ${memoToSign.payableDetails?.amount}`);
+        console.log(
+          `Buyer: Job ${job.id} — Amount: ${memoToSign.payableDetails?.amount}`,
+        );
         const { txnHash: subPayTx } = await job.paySubscription(
           `Subscription payment for ${SUBSCRIPTION_TIER}`,
         );
-        console.log(`Buyer: Job ${job.id} — Subscription paid (tx: ${subPayTx})`);
+        console.log(
+          `Buyer: Job ${job.id} — Subscription paid (tx: ${subPayTx})`,
+        );
 
-        // Fixed-price requirement — pay and advance to delivery (Scenario 3)
+        // Fixed-price requirement — pay and advance to delivery (Scenario 2)
       } else if (
         job.phase === AcpJobPhases.NEGOTIATION &&
         memoToSign?.type === MemoType.PAYABLE_REQUEST
       ) {
-        console.log(`Buyer: Job ${job.id} — Fixed-price requirement, paying now`);
+        console.log(
+          `Buyer: Job ${job.id} — Fixed-price requirement, paying now`,
+        );
         const payResult = await job.payAndAcceptRequirement("Payment for job");
-        console.log(`Buyer: Job ${job.id} — Paid and advanced to TRANSACTION phase (tx: ${payResult?.txnHash})`);
+        console.log(
+          `Buyer: Job ${job.id} — Paid and advanced to TRANSACTION phase (tx: ${payResult?.txnHash})`,
+        );
 
-        // Valid subscription — accept requirement without payment (Scenario 2)
+        // Active subscription path — accept requirement without payment
       } else if (
         job.phase === AcpJobPhases.NEGOTIATION &&
         memoToSign?.type === MemoType.MESSAGE &&
         memoToSign?.nextPhase === AcpJobPhases.TRANSACTION
       ) {
-        console.log(`Buyer: Job ${job.id} — Subscription active, accepting without payment`);
+        console.log(
+          `Buyer: Job ${job.id} — Subscription active, accepting without payment`,
+        );
         const { txnHash: signMemoTx } = await job.acceptRequirement(
           memoToSign,
           "Subscription verified, proceeding to delivery",
         );
-        console.log(`Buyer: Job ${job.id} — Advanced to TRANSACTION phase (tx: ${signMemoTx})`);
+        console.log(
+          `Buyer: Job ${job.id} — Advanced to TRANSACTION phase (tx: ${signMemoTx})`,
+        );
       } else if (job.phase === AcpJobPhases.COMPLETED) {
-        console.log(`Buyer: Job ${job.id} — Completed! Deliverable:`, job.deliverable);
+        console.log(
+          `Buyer: Job ${job.id} — Completed! Deliverable:`,
+          job.deliverable,
+        );
       } else if (job.phase === AcpJobPhases.REJECTED) {
-        console.log(`Buyer: Job ${job.id} — Rejected. Reason:`, job.rejectionReason);
+        console.log(
+          `Buyer: Job ${job.id} — Rejected. Reason:`,
+          job.rejectionReason,
+        );
       } else {
         console.log(
           `Buyer: Job ${job.id} — Unhandled event (phase: ${AcpJobPhases[job.phase]}, ` +
@@ -116,36 +129,47 @@ async function buyer() {
     showHiddenOfferings: true,
   });
 
+  console.log("Relevant agents:", relevantAgents);
+
   if (!relevantAgents || relevantAgents.length === 0) {
     console.error("No agents found");
     return;
   }
 
+  // Pick one of the agents based on your criteria (in this example we just pick the first one)
   const chosenAgent = relevantAgents[0];
+
+  // Pick one of the service offerings based on your criteria:
+  // - index 0: subscription offering
+  // - index 1: non-subscription (fixed-price) offering
   const subscriptionOffering = chosenAgent.jobOfferings[0];
   const fixedOffering = chosenAgent.jobOfferings[1];
 
   switch (SCENARIO) {
     case 1: {
-      console.log("--- Scenario 1: Subscription Offering ---\n");
-      const jobId1 = await subscriptionOffering.initiateJob(
+      const chosenJobOffering = subscriptionOffering;
+      const jobId = await chosenJobOffering.initiateJob(
+        // Requirement payload schema depends on your ACP service configuration.
+        // If your service requires fields, replace {} with the expected schema payload.
         {},
-        undefined,
-        new Date(Date.now() + 1000 * 60 * 15), // 15 min job expiry
+        undefined, // evaluator address, undefined fallback to empty address
+        new Date(Date.now() + 1000 * 60 * 15), // job expiry duration, minimum 5 minutes
         SUBSCRIPTION_TIER,
       );
-      console.log(`\nBuyer: [Scenario 1 — Subscription Offering] Job ${jobId1} initiated`);
+      console.log(`Buyer: [Scenario 1 — Subscription Offering] Job ${jobId} initiated`);
       break;
     }
 
     case 2: {
-      console.log("--- Scenario 2: Non-Subscription Offering (Fixed-Price) ---\n");
-      const jobId2 = await fixedOffering.initiateJob(
+      const chosenJobOffering = fixedOffering;
+      const jobId = await chosenJobOffering.initiateJob(
+        // Requirement payload schema depends on your ACP service configuration.
+        // If your service requires fields, replace {} with the expected schema payload.
         {},
-        undefined,
-        new Date(Date.now() + 1000 * 60 * 15), // 15 min job expiry
+        undefined, // evaluator address, undefined fallback to empty address
+        new Date(Date.now() + 1000 * 60 * 15), // job expiry duration, minimum 5 minutes
       );
-      console.log(`\nBuyer: [Scenario 2 — Fixed-Price Job] Job ${jobId2} initiated`);
+      console.log(`Buyer: [Scenario 2 — Fixed-Price Job] Job ${jobId} initiated`);
       break;
     }
 

examples/acp-base/subscription/seller.ts

@@ -1,11 +1,12 @@
 /**
  * Subscription Example - Seller (Provider)
  *
- * Demonstrates the subscription lifecycle from the provider side:
+ * Demonstrates provider-side handling for both subscription and fixed-price jobs:
  * 1. Listen for new jobs
- * 2. Check if the job's account has an active subscription (expiry > now)
- * 3. If no subscription, create a PAYABLE_REQUEST_SUBSCRIPTION memo
- * 4. Once subscription is paid, proceed with normal job flow
+ * 2. If job is fixed-price, accept and create PAYABLE_REQUEST
+ * 3. If job is subscription, check account status via getSubscriptionPaymentRequirement
+ * 4. If no active subscription, create PAYABLE_REQUEST_SUBSCRIPTION
+ * 5. Deliver once job reaches TRANSACTION phase
  */
 import AcpClient, {
   AcpContractClientV2,
@@ -67,8 +68,10 @@ async function seller() {
 }
 
 /**
- * Uses AcpClient.getSubscriptionPaymentRequirement to decide whether to
- * create a subscription payment request memo or just accept and create a requirement.
+ * Handles pricing logic for incoming jobs:
+ * - Fixed-price jobs: accept + create PAYABLE_REQUEST
+ * - Subscription jobs with active subscription: accept + create plain requirement
+ * - Subscription jobs without active subscription: accept + create PAYABLE_REQUEST_SUBSCRIPTION
  */
 async function handleSubscriptionCheck(acpClient: AcpClient, job: AcpJob) {
   const offeringName = job.name;