adapter-scaffold

name	adapter-scaffold
description	Scaffold new POS or payment adapter implementations. Use when adding support for Square, Toast, Clover, Stripe, or other integrations.
disable-model-invocation	false
allowed-tools	Read, Write, Bash(cd packages/*)

Adapter Scaffold Generator

This skill generates new POS or payment adapter implementations following the adapter pattern.

Workflow

1. Gather Requirements

   Ask user:

   • Adapter Type: POS or Payment?
   • Vendor Name: Square, Toast, Clover, Stripe, PayPal, etc.

   Example:

   Creating new adapter. Please provide:
   1. Adapter type (POS or Payment):
   2. Vendor name (e.g., Square, Toast, Stripe):
   

2. Read Adapter Interface

   For POS Adapters:

   # Read interface definition
   cat packages/pos-adapters/src/types.ts
   

   Interface includes:

   • testConnection(config) - Verify credentials and API access
   • pullMenu(config) - Fetch menu from POS system
   • pushOrder(config, order) - Send order to POS
   • parseWebhook(body, headers) - Parse webhook events
   • parseStockUpdate(webhookData) - Parse inventory updates

   For Payment Adapters:

   # Read interface definition
   cat packages/payment-adapters/src/types.ts
   

   Interface includes:

   • createPayment(config, amount, metadata) - Create payment intent
   • parseWebhook(body, headers) - Parse webhook events
   • refund(config, paymentId, amount) - Process refunds

3. Read Example Implementation

   For POS:

   # Use Square as reference
   cat packages/pos-adapters/src/square.ts
   

   For Payment:

   # Use Stripe as reference
   cat packages/payment-adapters/src/stripe.ts
   

4. Generate Adapter File

   Create new file at:

   • POS: packages/pos-adapters/src/{vendor}.ts
   • Payment: packages/payment-adapters/src/{vendor}.ts

   Template Structure:

   // AGPL-3.0 License Header
   // This file is part of OpenOrder.
   //
   // OpenOrder is free software: you can redistribute it and/or modify
   // it under the terms of the GNU Affero General Public License as published by
   // the Free Software Foundation, either version 3 of the License, or
   // (at your option) any later version.
   //
   // OpenOrder is distributed in the hope that it will be useful,
   // but WITHOUT ANY WARRANTY; without even the implied warranty of
   // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
   // GNU Affero General Public License for more details.
   //
   // You should have received a copy of the GNU Affero General Public License
   // along with OpenOrder. If not, see <https://www.gnu.org/licenses/>.
   
   import { IPosAdapter, PosConfig, PosMenu, PosOrder, PosWebhookEvent } from './types';
   
   export class {Vendor}Adapter implements IPosAdapter {
     async testConnection(config: PosConfig): Promise<boolean> {
       // TODO: Implement {Vendor} API connection test
       
       
       
         ();
     }
   
      (: ): <> {
       
       
       
       
       
         ();
     }
   
      (: , : ): <> {
       
       
       
       
       
         ();
     }
   
     (: , : <, >):  |  {
       
       
       
       
       
         ();
     }
   
     (: ): { : ; :  } |  {
       
       
       
       
         ();
     }
   }
   

5. Update Package Exports

   Add to packages/{pos|payment}-adapters/src/index.ts:

   export * from './{vendor}';
   

6. Generate Test Stub

   Create packages/{pos|payment}-adapters/src/{vendor}.test.ts:

   import { describe, it, expect } from 'vitest';
   import { {Vendor}Adapter } from './{vendor}';
   
   describe('{Vendor}Adapter', () => {
     const adapter = new {Vendor}Adapter();
   
     describe('testConnection', () => {
       it('should validate API credentials', async () => {
         // TODO: Add test with valid credentials
         // TODO: Add test with invalid credentials
       });
     });
   
     describe('pullMenu', () => {
       it('should fetch and transform menu data', async () => {
         // TODO: Mock API response
         // TODO: Verify transformation to PosMenu format
       });
     });
   
     describe('pushOrder', () => {
       it('should create order in {Vendor} system', async () => {
         // TODO: Mock API call
         // TODO: Verify order format
       });
     });
   
     (,  {
       (,  {
         
         
       });
   
       (,  {
         
       });
     });
   });
   

7. Provide Implementation Guidance

   Critical Security Requirements:

   • Webhook Signature Verification:

     // Always verify webhooks before processing
     const signature = headers['x-{vendor}-signature'];
     const expectedSignature = crypto
       .createHmac('sha256', config.webhookSecret)
       .update(JSON.stringify(body))
       .digest('hex');
     
     if (signature !== expectedSignature) {
       return null; // Invalid signature
     }
     

   • Encrypted Config Storage:

     // Sensitive keys stored in encrypted JSONB
     interface {Vendor}Config extends PosConfig {
       apiKey: string;      // Encrypted at rest
       apiSecret: string;   // Encrypted at rest
       locationId: string;  // OK to be plaintext
     }
     

   • Error Handling:

     try {
       const response = await fetch('{vendor-api-url}', {
         headers: { Authorization: `Bearer ${config.apiKey}` }
       });
     
        (!response.) {
           ();
       }
     
         response.();
     }  (error) {
       
       .(, error);
         ();
     }
     

8. Remind About Next Steps

   After scaffolding:

   • Read vendor API documentation
   • Set up test account with vendor
   • Implement each method incrementally
   • Add integration tests with real API (use test mode)
   • Update apps/api/src/services/pos-service.ts to register new adapter
   • Add vendor to dashboard settings UI
   • Document required config fields in docs/

Common Pitfalls

1. Forgetting AGPL Header Every new file must include the license header.

2. Incomplete Interface Implementation All methods must be implemented, even if just throwing "Not implemented" initially.

3. Hardcoding Credentials Never put API keys in code - always use config parameter.

4. Skipping Webhook Verification Unverified webhooks are a security risk - always validate signatures.

5. Not Handling Pagination Many POS APIs paginate menu/order data - implement pagination handling.

6. Ignoring Rate Limits Implement exponential backoff for API calls to respect rate limits.

Testing Checklist

Before marking adapter complete:

• All interface methods implemented
• Webhook signature verification working
• Error handling for network failures
• Unit tests for all methods
• Integration tests with test API credentials
• Documentation for required config fields
• AGPL header present
• Exported from package index
• Registered in API service layer