feat: add auto-release feature for escrows at expiry

Author: ralyodio

src/app/api/cron/monitor-payments/escrow-monitor.ts

@@ -121,17 +121,42 @@ async function autoRefundExpiredFundedEscrows(
 ): Promise<void> {
   const { data: expiredFundedEscrows } = await supabase
     .from('escrows')
-    .select('id, escrow_address, chain, amount, deposited_amount, depositor_address, expires_at')
+    .select('id, escrow_address, chain, amount, deposited_amount, depositor_address, expires_at, beneficiary_address, allow_auto_release')
     .eq('status', 'funded')
     .lt('expires_at', now.toISOString())
     .limit(20);
 
   if (!expiredFundedEscrows || expiredFundedEscrows.length === 0) return;
 
-  console.log(`Auto-refunding ${expiredFundedEscrows.length} expired funded escrows`);
+  console.log(`Processing ${expiredFundedEscrows.length} expired funded escrows (auto-release/auto-refund)`);
 
   for (const escrow of expiredFundedEscrows) {
     try {
+      if (escrow.allow_auto_release) {
+        await supabase
+          .from('escrows')
+          .update({
+            status: 'released',
+            released_at: now.toISOString(),
+          })
+          .eq('id', escrow.id)
+          .eq('status', 'funded');
+
+        await supabase.from('escrow_events').insert({
+          escrow_id: escrow.id,
+          event_type: 'released',
+          actor: 'system',
+          details: {
+            reason: 'Escrow expired — auto-release enabled',
+            release_to: escrow.beneficiary_address,
+            amount: escrow.deposited_amount || escrow.amount,
+          },
+        });
+
+        console.log(`Escrow ${escrow.id} expired while funded — auto-released`);
+        continue;
+      }
+
       await supabase
         .from('escrows')
         .update({

src/app/api/cron/monitor-payments/series-monitor.ts

@@ -87,6 +87,7 @@ export async function monitorSeries(
             period: nextPeriod,
             description: series.description || undefined,
           },
+          allow_auto_release: Boolean(series.allow_auto_release),
         }, isPaidTier);
 
         if (escrowResult.success) {

src/app/api/escrow/[id]/auto-release/route.ts

@@ -0,0 +1,56 @@
+/**
+ * POST /api/escrow/:id/auto-release — Toggle auto-release on expiry
+ * Auth: release_token (depositor only)
+ */
+
+import { NextRequest, NextResponse } from 'next/server';
+import { createClient } from '@supabase/supabase-js';
+import { setEscrowAutoRelease } from '@/lib/escrow';
+
+function getSupabase() {
+  const url = process.env.NEXT_PUBLIC_SUPABASE_URL;
+  const key = process.env.SUPABASE_SERVICE_ROLE_KEY;
+  if (!url || !key) throw new Error('Supabase not configured');
+  return createClient(url, key);
+}
+
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ id: string }> }
+) {
+  try {
+    const { id } = await params;
+    const body = await request.json();
+
+    if (!body.release_token) {
+      return NextResponse.json(
+        { error: 'release_token is required' },
+        { status: 400 }
+      );
+    }
+
+    if (typeof body.allow_auto_release !== 'boolean') {
+      return NextResponse.json(
+        { error: 'allow_auto_release must be a boolean' },
+        { status: 400 }
+      );
+    }
+
+    const supabase = getSupabase();
+    const result = await setEscrowAutoRelease(supabase, id, body.release_token, body.allow_auto_release);
+
+    if (!result.success) {
+      const status = result.error?.includes('Unauthorized') ? 403 :
+        result.error?.includes('not found') ? 404 : 400;
+      return NextResponse.json({ error: result.error }, { status });
+    }
+
+    return NextResponse.json(result.escrow);
+  } catch (error) {
+    console.error('Failed to update escrow auto-release:', error);
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    );
+  }
+}

src/app/api/escrow/route.ts

@@ -88,6 +88,7 @@ export async function GET(request: NextRequest) {
     const apiKeyHeader = request.headers.get('x-api-key');
     let merchantId: string | undefined;
     let businessIds: string[] | undefined;
+    let scopedWalletAddresses: string[] = [];
 
     if (authHeader || apiKeyHeader) {
       try {
@@ -115,31 +116,118 @@ export async function GET(request: NextRequest) {
 
       if (businesses && businesses.length > 0) {
         businessIds = businesses.map((b: { id: string }) => b.id);
-      } else {
-        // Merchant has no businesses — return empty
-        return NextResponse.json({ escrows: [], total: 0, limit: filters.limit, offset: filters.offset });
       }
+
+      // Also scope by wallets owned by this merchant (global + business wallets)
+      const walletAddressSet = new Set<string>();
+
+      const { data: merchantWallets } = await supabase
+        .from('merchant_wallets')
+        .select('wallet_address')
+        .eq('merchant_id', merchantId)
+        .eq('is_active', true);
+
+      for (const row of merchantWallets || []) {
+        if (row.wallet_address) walletAddressSet.add(row.wallet_address);
+      }
+
+      if (businessIds && businessIds.length > 0) {
+        const { data: businessWallets } = await supabase
+          .from('business_wallets')
+          .select('wallet_address')
+          .in('business_id', businessIds)
+          .eq('is_active', true);
+
+        for (const row of businessWallets || []) {
+          if (row.wallet_address) walletAddressSet.add(row.wallet_address);
+        }
+      }
+
+      scopedWalletAddresses = Array.from(walletAddressSet);
     }
 
-    // Must have at least one scoping filter (don't allow listing all escrows)
-    const hasFilter = filters.status || filters.depositor_address ||
-      filters.beneficiary_address || filters.business_id || businessIds;
-    if (!hasFilter) {
+    // Must have a scoping filter (status alone must NOT allow listing all escrows)
+    const hasScope = Boolean(
+      filters.depositor_address ||
+      filters.beneficiary_address ||
+      filters.business_id ||
+      (businessIds && businessIds.length > 0) ||
+      (scopedWalletAddresses && scopedWalletAddresses.length > 0)
+    );
+    if (!hasScope) {
       return NextResponse.json(
-        { error: 'At least one filter required (status, depositor, beneficiary, or business_id)' },
+        { error: 'A scoping filter is required (depositor, beneficiary, business_id, or authenticated account scope)' },
         { status: 400 }
       );
     }
 
-    const result = await listEscrows(supabase, { ...filters, business_ids: businessIds } as any);
+    const offset = Number(filters.offset || 0);
+    const limit = Number(filters.limit || 20);
 
-    if (!result.success) {
-      return NextResponse.json({ error: result.error }, { status: 500 });
+    // If the caller explicitly scopes by depositor/beneficiary/business_id, keep direct behavior.
+    const hasExplicitPartyScope = Boolean(filters.depositor_address || filters.beneficiary_address || filters.business_id);
+    if (hasExplicitPartyScope) {
+      const result = await listEscrows(supabase, { ...filters, business_ids: businessIds } as any);
+
+      if (!result.success) {
+        return NextResponse.json({ error: result.error }, { status: 500 });
+      }
+
+      return NextResponse.json({
+        escrows: result.escrows,
+        total: result.total,
+        limit: filters.limit,
+        offset: filters.offset,
+      });
+    }
+
+    // Implicit authenticated account scope: union of business escrows + wallet-party escrows.
+    const aggregate = new Map<string, any>();
+    const queries: Array<Promise<{ success: boolean; escrows?: any[]; total?: number; error?: string }>> = [];
+
+    if (businessIds && businessIds.length > 0) {
+      queries.push(listEscrows(supabase, {
+        ...filters,
+        business_ids: businessIds,
+        limit: 500,
+        offset: 0,
+      } as any));
+    }
+
+    if (scopedWalletAddresses.length > 0) {
+      queries.push(listEscrows(supabase, {
+        ...filters,
+        depositor_addresses: scopedWalletAddresses,
+        limit: 500,
+        offset: 0,
+      } as any));
+      queries.push(listEscrows(supabase, {
+        ...filters,
+        beneficiary_addresses: scopedWalletAddresses,
+        limit: 500,
+        offset: 0,
+      } as any));
+    }
+
+    const results = await Promise.all(queries);
+    for (const result of results) {
+      if (!result.success) {
+        return NextResponse.json({ error: result.error }, { status: 500 });
+      }
+      for (const escrow of result.escrows || []) {
+        aggregate.set(escrow.id, escrow);
+      }
     }
 
+    const mergedEscrows = Array.from(aggregate.values()).sort((a, b) =>
+      new Date(b.created_at).getTime() - new Date(a.created_at).getTime()
+    );
+
+    const pagedEscrows = mergedEscrows.slice(offset, offset + limit);
+
     return NextResponse.json({
-      escrows: result.escrows,
-      total: result.total,
+      escrows: pagedEscrows,
+      total: mergedEscrows.length,
       limit: filters.limit,
       offset: filters.offset,
     });

src/app/api/escrow/series/route.ts

@@ -33,6 +33,7 @@ export async function POST(request: NextRequest) {
       beneficiary_address,
       depositor_address,
       beneficiary_email,
+      allow_auto_release = false,
     } = body;
 
     // Validate required fields before touching DB
@@ -87,6 +88,7 @@ export async function POST(request: NextRequest) {
         max_periods: max_periods || null,
         beneficiary_address,
         depositor_address,
+        allow_auto_release: Boolean(allow_auto_release),
       })
       .select()
       .single();
@@ -115,6 +117,7 @@ export async function POST(request: NextRequest) {
           period: 1,
           description: description || undefined,
         },
+        allow_auto_release: Boolean(allow_auto_release),
         ...(customer_email ? { depositor_email: customer_email } : {}),
         ...(beneficiary_email ? { beneficiary_email } : {}),
       };

src/app/escrow/create/page.tsx

@@ -50,6 +50,7 @@ interface CreatedEscrow {
   status: string;
   release_token: string;
   beneficiary_token: string;
+  allow_auto_release?: boolean;
   expires_at: string;
   created_at: string;
   metadata: Record<string, unknown>;
@@ -76,6 +77,7 @@ export default function CreateEscrowPage() {
     description: '',
     expires_in_hours: 168,
     business_id: '',
+    allow_auto_release: false,
   });
 
   // Recurring escrow state
@@ -272,6 +274,7 @@ export default function CreateEscrowPage() {
         depositor_address: formData.depositor_address.trim(),
         beneficiary_address: formData.beneficiary_address.trim(),
         expires_in_hours: formData.expires_in_hours,
+        allow_auto_release: formData.allow_auto_release,
       };
 
       if (formData.arbiter_address.trim()) {
@@ -487,6 +490,7 @@ export default function CreateEscrowPage() {
                   `Depositor: ${createdEscrow.depositor_address}`,
                   `Beneficiary: ${createdEscrow.beneficiary_address}`,
                   `Expires: ${new Date(createdEscrow.expires_at).toLocaleString()}`,
+                  `Auto-release at expiry: ${createdEscrow.allow_auto_release ? 'Enabled' : 'Disabled'}`,
                   `Release Token: ${createdEscrow.release_token}`,
                   `Beneficiary Token: ${createdEscrow.beneficiary_token}`,
                   ...(createdEscrow.fee_amount ? [`Commission: ${createdEscrow.fee_amount} ${createdEscrow.chain}`] : []),
@@ -661,6 +665,12 @@ export default function CreateEscrowPage() {
                   {new Date(createdEscrow.expires_at).toLocaleString()}
                 </span>
               </div>
+              <div>
+                <span className="text-gray-500 dark:text-gray-400">Auto-release at expiry:</span>
+                <span className="ml-2 text-gray-900 dark:text-white">
+                  {createdEscrow.allow_auto_release ? 'Enabled' : 'Disabled'}
+                </span>
+              </div>
               {createdEscrow.fee_amount != null && createdEscrow.fee_amount > 0 && (
                 <div className="bg-amber-50 dark:bg-amber-900/10 border border-amber-200 dark:border-amber-800 rounded-lg p-3">
                   <span className="text-sm font-medium text-amber-800 dark:text-amber-300">Platform Commission:</span>
@@ -1029,6 +1039,21 @@ export default function CreateEscrowPage() {
             </select>
           </div>
 
+          <div className="border border-gray-200 dark:border-gray-700 rounded-lg p-4">
+            <label className="flex items-start gap-3 cursor-pointer">
+              <input
+                type="checkbox"
+                checked={formData.allow_auto_release}
+                onChange={(e) => setFormData({ ...formData, allow_auto_release: e.target.checked })}
+                className="mt-0.5 w-4 h-4 text-blue-600 bg-white dark:bg-gray-900 border-gray-300 dark:border-gray-600 rounded focus:ring-blue-500"
+              />
+              <span className="text-sm text-gray-700 dark:text-gray-300">
+                <span className="font-medium">Allow auto-release</span>
+                {' '}to release funds to the beneficiary when the escrow expiry is reached (instead of auto-refund).
+              </span>
+            </label>
+          </div>
+
           {/* Description */}
           <div>
             <label htmlFor="description" className="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-2">