feat: webhook DLQ filters, SDK sandbox mocks, SDK playground, API version notices

backend/src/index.ts

@@ -25,6 +25,8 @@ import allowancesRouter from './routes/allowances.js';
 import { formsRouter } from './routes/forms.js';
 import { twoFactorAuthRouter } from './routes/2fa.js';
 import { webhooksRouter } from './routes/webhooks.js';
+import webhooksDlqRouter from './routes/webhooks-dlq.js';
+import { apiVersionsRouter } from './routes/api-versions.js';
 import { webhookHandlersRouter } from './routes/webhookHandlers.js';
 import { webhookJsonParser } from './middleware/webhookVerification.js';
 import { startJobs, getJobScheduler } from './jobs/index.js';
@@ -380,6 +382,8 @@ app.use('/api/v1/gdpr', gdprRouter);
 app.use('/api/v1/escrow', escrowRouter);
 app.use('/api/v1/multisig', multisigRouter);
 app.use('/api/v1/webhooks', webhooksRouter);
+app.use('/api/v1/webhooks', webhooksDlqRouter);
+app.use('/api/v1/api-versions', apiVersionsRouter);
 app.use('/api/v1/fraud-detection', fraudDetectionRouter);
 app.use('/api/v1/bridge', bridgeRouter);
 app.use('/api/v1/tokenization', tokenizationRouter);

backend/src/middleware/versioning.ts

@@ -57,5 +57,73 @@ export const versionMiddleware = (req: Request, res: Response, next: NextFunctio
   req.apiVersion = version;
   res.setHeader('X-API-Version', version);
 
+  const info = versionRegistry.get(version);
+  if (info?.deprecated) {
+    res.setHeader('Deprecation', 'true');
+    if (info.sunsetDate) {
+      res.setHeader('Sunset', new Date(info.sunsetDate).toUTCString());
+    }
+    if (info.alternativeVersion) {
+      res.setHeader('Link', `</api/${info.alternativeVersion}/>; rel="successor-version"`);
+    }
+  }
+
   next();
 };
+
+export interface ApiVersion {
+  version: string;
+  description?: string;
+  changelogUrl?: string;
+  alternativeVersion?: string;
+  deprecated: boolean;
+  sunsetDate?: string;
+  registeredAt: string;
+}
+
+export interface RegisterVersionInput {
+  version: string;
+  description?: string;
+  changelogUrl?: string;
+  alternativeVersion?: string;
+}
+
+const versionRegistry = new Map<string, ApiVersion>();
+
+function compareVersions(a: string, b: string): number {
+  return Number(a.replace(/^v/, '')) - Number(b.replace(/^v/, ''));
+}
+
+export function registerVersion(input: RegisterVersionInput): ApiVersion {
+  const existing = versionRegistry.get(input.version);
+  const info: ApiVersion = {
+    ...existing,
+    ...input,
+    deprecated: existing?.deprecated ?? false,
+    sunsetDate: existing?.sunsetDate,
+    registeredAt: existing?.registeredAt ?? new Date().toISOString(),
+  };
+  versionRegistry.set(info.version, info);
+  return info;
+}
+
+export function getVersion(version: string): ApiVersion | undefined {
+  return versionRegistry.get(version);
+}
+
+export function listVersions(): ApiVersion[] {
+  return Array.from(versionRegistry.values()).sort((a, b) => compareVersions(a.version, b.version));
+}
+
+export function deprecateVersion(version: string, sunsetDate: Date, alternativeVersion?: string): ApiVersion {
+  const info = versionRegistry.get(version);
+  if (!info) {
+    throw new Error(`Version '${version}' is not registered.`);
+  }
+  info.deprecated = true;
+  info.sunsetDate = sunsetDate.toISOString();
+  if (alternativeVersion) {
+    info.alternativeVersion = alternativeVersion;
+  }
+  return info;
+}

backend/src/routes/webhooks-dlq.ts

@@ -75,10 +75,11 @@ router.get('/delivery-logs/export.csv', (req: Request, res: Response) => {
 
 router.get('/dlq', (req: Request, res: Response) => {
   syncDLQFromDeliveryLogs();
-  const { merchantId, endpointId, failureCategory } = req.query as Record<string, string>;
+  const { merchantId, endpointId, eventType, failureCategory } = req.query as Record<string, string>;
   const entries = listDLQ({
     merchantId,
     endpointId,
+    eventType,
     failureCategory: failureCategory as Parameters<typeof listDLQ>[0]['failureCategory'],
   });
   res.json({ count: entries.length, entries });

backend/src/services/webhooks/dead-letter-queue.ts

@@ -85,12 +85,14 @@ export function enqueueDeadLetter(log: DeliveryLog): DeadLetterEntry {
 export function listDLQ(filters: {
   merchantId?: string;
   endpointId?: string;
+  eventType?: string;
   failureCategory?: FailureCategory;
 } = {}): DeadLetterEntry[] {
   return Array.from(dlqEntries.values()).filter((e) => {
     if (e.purgedAt) return false;
     if (filters.merchantId && e.merchantId !== filters.merchantId) return false;
     if (filters.endpointId && e.endpointId !== filters.endpointId) return false;
+    if (filters.eventType && e.eventType !== filters.eventType) return false;
     if (filters.failureCategory && e.failureCategory !== filters.failureCategory) return false;
     return true;
   });

docs/sdk/PLAYGROUND.md

@@ -0,0 +1,28 @@
+# SDK Playground
+
+The SDK playground is a set of small, runnable examples that exercise the
+`@agenticpay/sdk` client against a running API (the sandbox is a good target).
+
+## Examples
+
+| id | Description | Args |
+|---|---|---|
+| `sandbox-status` | Check sandbox health | none |
+| `refund-policy` | Fetch a merchant's refund policy | `<merchantId>` |
+| `merchant-splits` | List a merchant's payment splits | `<merchantId>` |
+| `verification` | Fetch a work verification | `<verificationId>` |
+
+## Usage
+
+```ts
+import { createAgenticPaySDK, getPlaygroundExample, PLAYGROUND_EXAMPLES } from '@agenticpay/sdk';
+
+const sdk = createAgenticPaySDK({ baseUrl: process.env.AGENTICPAY_BASE_URL ?? 'http://localhost:3000/api/v1', apiKey: process.env.AGENTICPAY_API_KEY });
+
+const example = getPlaygroundExample('sandbox-status');
+console.log(await example.run(sdk, []));
+
+console.log(PLAYGROUND_EXAMPLES.map((item) => item.id));
+```
+
+Unknown example ids and missing arguments throw descriptive errors.

packages/sdk/src/index.ts

@@ -8,6 +8,8 @@ import { AgenticPayClientOptions } from './types.js';
 export * from './types.js';
 export * from './errors.js';
 export * from './auth.js';
+export { SANDBOX_MOCK_PAYMENTS, createMockPaymentResult } from './sandbox.js';
+export * from './playground.js';
 
 export class AgenticPaySDK {
   readonly client: AgenticPayClient;

packages/sdk/src/playground.ts

@@ -0,0 +1,52 @@
+import type { AgenticPaySDK } from './index.js';
+import { SandboxApi } from './sandbox.js';
+
+export interface PlaygroundExample {
+  id: string;
+  title: string;
+  description: string;
+  run: (sdk: AgenticPaySDK, args: string[]) => Promise<unknown>;
+}
+
+export const PLAYGROUND_EXAMPLES: PlaygroundExample[] = [
+  {
+    id: 'sandbox-status',
+    title: 'Sandbox status',
+    description: 'Check whether the sandbox environment is healthy.',
+    run: (sdk) => new SandboxApi(sdk.client).getStatus(),
+  },
+  {
+    id: 'refund-policy',
+    title: 'Refund policy',
+    description: 'Fetch the refund policy for a merchant. Args: <merchantId>.',
+    run: (sdk, args) => sdk.refunds.getPolicy(requireArg(args, 0, 'merchantId')),
+  },
+  {
+    id: 'merchant-splits',
+    title: 'Merchant splits',
+    description: 'List payment split configs for a merchant. Args: <merchantId>.',
+    run: (sdk, args) => sdk.payments.listMerchantSplits(requireArg(args, 0, 'merchantId')),
+  },
+  {
+    id: 'verification',
+    title: 'Get verification',
+    description: 'Fetch a work verification by id. Args: <verificationId>.',
+    run: (sdk, args) => sdk.verification.getVerification(requireArg(args, 0, 'verificationId')),
+  },
+];
+
+export function getPlaygroundExample(id: string): PlaygroundExample {
+  const example = PLAYGROUND_EXAMPLES.find((item) => item.id === id);
+  if (!example) {
+    throw new Error(`Unknown playground example '${id}'. Available: ${PLAYGROUND_EXAMPLES.map((item) => item.id).join(', ')}`);
+  }
+  return example;
+}
+
+function requireArg(args: string[], index: number, name: string): string {
+  const value = args[index];
+  if (!value) {
+    throw new Error(`Missing required argument '${name}'`);
+  }
+  return value;
+}

packages/sdk/src/sandbox.ts

@@ -22,6 +22,31 @@ export type SandboxPaymentResult = {
   timestamp: string;
 };
 
+export const SANDBOX_MOCK_PAYMENTS: SandboxPaymentResult[] = [
+  {
+    transactionHash: 'mock_tx_0001',
+    status: 'success',
+    ledger: 1_000_001,
+    timestamp: '2026-01-01T00:00:00.000Z',
+  },
+  {
+    transactionHash: 'mock_tx_0002',
+    status: 'success',
+    ledger: 1_000_002,
+    timestamp: '2026-01-02T00:00:00.000Z',
+  },
+];
+
+/** Build a deterministic mock payment result for offline sandbox tests. */
+export function createMockPaymentResult(input: SandboxPaymentInput, ledger = 1_000_000): SandboxPaymentResult {
+  return {
+    transactionHash: `mock_${input.from}_${input.to}_${input.amount}_${input.currency}`,
+    status: 'success',
+    ledger,
+    timestamp: new Date(0).toISOString(),
+  };
+}
+
 export class SandboxApi {
   constructor(private readonly client: AgenticPayClient) {}