@paykit-sdk/paypal 1.0.0

package/README.md

@@ -0,0 +1,207 @@
+# @paykit-sdk/paypal
+
+PayPal provider for PayKit
+
+## Quick Start
+
+```typescript
+import { createEndpointHandlers, PayKit } from '@paykit-sdk/core';
+import { paypal, createPayPal } from '@paykit-sdk/paypal';
+
+// Method 1: Using environment variables
+const provider = paypal(); // Ensure PAYPAL_CLIENT_ID, PAYPAL_CLIENT_SECRET, PAYPAL_SANDBOX are set
+
+// Method 2: Direct configuration
+const provider = createPayPal({
+  clientId: process.env.PAYPAL_CLIENT_ID,
+  clientSecret: process.env.PAYPAL_CLIENT_SECRET,
+  isSandbox: true,
+});
+
+export const paykit = new PayKit(provider);
+export const endpoints = createEndpointHandlers(paykit);
+```
+
+### Next.js Catch All API Route (/api/paykit/[...endpoint]/route.ts)
+
+```typescript
+import { endpoints } from '@/lib/paykit';
+import { EndpointPath } from '@paykit-sdk/core';
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function POST(
+  request: NextRequest,
+  { params }: { params: { endpoint: string[] } },
+) {
+  try {
+    // Construct the endpoint path with full type safety
+    const endpoint = ('/' + params.endpoint.join('/')) as EndpointPath;
+    const handler = endpoints[endpoint];
+
+    if (!handler) {
+      return NextResponse.json({ message: 'Endpoint not found' }, { status: 404 });
+    }
+
+    // Parse request body
+    const body = await request.json();
+    const { args } = body;
+
+    const result = await handler(...args);
+
+    return NextResponse.json({ result });
+  } catch (error) {
+    console.error('PayKit API Error:', error);
+    return NextResponse.json(
+      { message: error instanceof Error ? error.message : 'Internal server error' },
+      { status: 500 },
+    );
+  }
+}
+```
+
+### Next.js Webhooks (/api/paykit/webhooks/route.ts)
+
+```typescript
+import { paykit } from '@/lib/paykit';
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function POST(request: NextRequest) {
+  const webhookSecret = process.env.PAYPAL_WEBHOOK_ID;
+
+  if (!webhookSecret) {
+    return NextResponse.json({ error: 'Webhook secret not configured' }, { status: 500 });
+  }
+
+  const webhook = paykit.webhooks
+    .setup({ webhookSecret })
+    .on('customer.created', async event => {
+      console.log('Customer created:', event.data);
+    })
+    .on('subscription.created', async event => {
+      console.log('Subscription created:', event.data);
+    })
+    .on('payment.created', async event => {
+      console.log('Payment created:', event.data);
+    })
+    .on('refund.created', async event => {
+      console.log('Refund created:', event.data);
+    });
+
+  const body = await request.text();
+  const headers = Object.fromEntries(request.headers.entries());
+  const url = request.url;
+  await webhook.handle({ body, headers, fullUrl: url });
+
+  // Return immediately, processing happens in background
+  return NextResponse.json({ success: true });
+}
+```
+
+### Express.js with Webhook Handler
+
+```typescript
+import { endpoints, paykit } from '@/lib/paykit';
+import { EndpointPath } from '@paykit-sdk/core';
+import express from 'express';
+
+const app = express();
+
+// IMPORTANT: Webhook route must come BEFORE express.json() middleware
+// This ensures we get the raw body for signature verification
+app.post(
+  '/api/webhooks/paypal',
+  express.raw({ type: 'application/json' }),
+  async (req, res) => {
+    try {
+      const webhookSecret = process.env.PAYPAL_WEBHOOK_ID;
+
+      if (!webhookSecret) {
+        return res.status(500).json({ error: 'Webhook secret not configured' });
+      }
+
+      const webhook = paykit.webhooks
+        .setup({ webhookSecret })
+        .on('customer.created', async event => {
+          console.log('Customer created:', event.data);
+        })
+        .on('subscription.created', async event => {
+          console.log('Subscription created:', event.data);
+        })
+        .on('payment.created', async event => {
+          console.log('Payment created:', event.data);
+        })
+        .on('refund.created', async event => {
+          console.log('Refund created:', event.data);
+        });
+
+      const body = req.body; // Raw buffer from express.raw()
+      const headers = req.headers;
+      const url = req.url;
+      await webhook.handle({ body, headers, fullUrl: url });
+
+      // Return immediately, processing happens in background
+      res.json({ success: true });
+    } catch (error) {
+      console.error('Webhook error:', error);
+      res.status(500).json({
+        message: error instanceof Error ? error.message : 'Webhook processing failed',
+      });
+    }
+  },
+);
+
+// Regular API routes use JSON middleware
+app.use(express.json());
+
+app.post('/api/paykit/*', async (req, res) => {
+  try {
+    const endpoint = req.path.replace('/api/paykit', '') as EndpointPath;
+    const handler = endpoints[endpoint];
+
+    if (!handler) {
+      return res.status(404).json({ message: 'Endpoint not found' });
+    }
+
+    const { args } = req.body;
+    const result = await handler(...args);
+
+    res.json({ result });
+  } catch (error) {
+    res.status(500).json({
+      message: error instanceof Error ? error.message : 'Internal server error',
+    });
+  }
+});
+
+app.listen(3000, () => {
+  console.log('Server running on port 3000');
+});
+```
+
+## Subscription Management
+
+```typescript
+// Update subscription
+await paykit.subscriptions.update('sub_123', {
+  metadata: { plan: 'enterprise' },
+});
+
+// Cancel subscription
+await paykit.subscriptions.cancel('sub_123');
+```
+
+## Environment Variables
+
+```bash
+PAYPAL_CLIENT_ID=your_client_id
+PAYPAL_CLIENT_SECRET=your_client_secret
+PAYPAL_WEBHOOK_ID=your_webhook_id
+```
+
+## Support
+
+- [PayPal Documentation](https://developer.paypal.com/docs/api/overview/)
+
+## License
+
+ISC

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@paykit-sdk/paypal",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "keywords": [],
+  "author": "Emmanuel Odii",
+  "license": "ISC",
+  "peerDependencies": {
+    "@paykit-sdk/core": ">=1.1.92"
+  },
+  "devDependencies": {
+    "@paykit-sdk/core": "1.1.92"
+  },
+  "dependencies": {
+    "@paypal/paypal-server-sdk": "^1.1.0",
+    "zod": "^3.24.2"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}

package/src/controllers/subscription.ts

@@ -0,0 +1,118 @@
+import { CreateSubscriptionSchema } from '@paykit-sdk/core';
+import { ApiResponse, CustomError } from '@paypal/paypal-server-sdk';
+import { BaseController } from '@paypal/paypal-server-sdk/dist/types/controllers/baseController';
+import {
+  createSubscriptionApticSchema,
+  resumeSubscriptionApticSchemaRequest,
+  resumeSubscriptionApticSchemaRequest as cancelSubscriptionApticSchemaRequest,
+  subscriptionApticSchema,
+} from '../schema';
+
+export class SubscriptionsController extends BaseController {
+  private catchAllErrors(req: ReturnType<BaseController['createRequest']>) {
+    req.throwOn(
+      400,
+      CustomError,
+      'Request is not well-formed, syntactically incorrect, or violates schema.',
+    );
+    req.throwOn(
+      401,
+      CustomError,
+      'Authentication failed due to missing authorization header, or invalid authentication credentials.',
+    );
+    req.throwOn(
+      422,
+      CustomError,
+      'The requested action could not be performed, semantically incorrect, or failed business validation.',
+    );
+  }
+
+  /**
+   * @return Response from the API call
+   */
+  async createSubscription({
+    body,
+  }: {
+    body: CreateSubscriptionSchema;
+  }): Promise<ApiResponse<any>> {
+    const req = this.createRequest('POST', '/v1/billing/subscriptions');
+    const mapped = req.prepareArgs({ body: [body, createSubscriptionApticSchema] });
+    req.header('Content-Type', 'application/json');
+    req.header('PayPal-Request-Id', Math.random().toString(36).substring(2, 15));
+
+    req.json(mapped.body);
+    this.catchAllErrors(req);
+    req.authenticate([{ oauth2: true }]);
+    return req.callAsJson(subscriptionApticSchema);
+  }
+
+  /**
+   * @returns Response from the API call
+   */
+  async resumeSubscription({
+    body,
+    subscriptionId,
+  }: {
+    body: { reason: string };
+    subscriptionId: string;
+  }) {
+    const req = this.createRequest(
+      'POST',
+      `v1/billing/subscriptions/${subscriptionId}/activate `,
+    );
+    const mapped = req.prepareArgs({
+      body: [body, resumeSubscriptionApticSchemaRequest],
+    });
+    req.header('Content-Type', 'application/json');
+    req.header('PayPal-Request-Id', Math.random().toString(36).substring(2, 15));
+
+    req.json(mapped.body);
+    this.catchAllErrors(req);
+    req.authenticate([{ oauth2: true }]);
+  }
+
+  async retrieveSubscription({ subscriptionId }: { subscriptionId: string }) {
+    const req = this.createRequest('GET', `v1/billing/subscriptions/${subscriptionId}`);
+    req.header('PayPal-Request-Id', Math.random().toString(36).substring(2, 15));
+    this.catchAllErrors(req);
+    req.authenticate([{ oauth2: true }]);
+    return req.callAsJson(subscriptionApticSchema);
+  }
+
+  async cancelSubscription({
+    subscriptionId,
+    reason,
+  }: {
+    subscriptionId: string;
+    reason: string;
+  }) {
+    const req = this.createRequest(
+      'POST',
+      `v1/billing/subscriptions/${subscriptionId}/cancel`,
+    );
+    const mapped = req.prepareArgs({
+      body: [reason, cancelSubscriptionApticSchemaRequest],
+    });
+    req.header('PayPal-Request-Id', Math.random().toString(36).substring(2, 15));
+    req.json(mapped.body);
+    this.catchAllErrors(req);
+    req.authenticate([{ oauth2: true }]);
+    return req.callAsJson(subscriptionApticSchema);
+  }
+
+  async updateSubscription({
+    subscriptionId,
+    metadata,
+  }: {
+    subscriptionId: string;
+    metadata: Record<string, unknown>;
+  }) {
+    const req = this.createRequest('PATCH', `v1/billing/subscriptions/${subscriptionId}`);
+    req.header('PayPal-Request-Id', Math.random().toString(36).substring(2, 15));
+
+    req.json({ op: 'replace', path: '/custom_id', value: JSON.stringify(metadata) });
+
+    this.catchAllErrors(req);
+    req.authenticate([{ oauth2: true }]);
+  }
+}

package/src/controllers/webhook.ts

@@ -0,0 +1,45 @@
+import { ApiResponse, CustomError } from '@paypal/paypal-server-sdk';
+import { BaseController } from '@paypal/paypal-server-sdk/dist/types/controllers/baseController';
+import { VerifyWebhookSchema, verifyWebhookSchema } from '../schema';
+
+export class WebhookController extends BaseController {
+  async verifyWebhook(body: {
+    authAlgo: string;
+    certUrl: string;
+    transmissionId: string;
+    transmissionSig: string;
+    transmissionTime: string;
+    webhookId: string;
+    webhookEvent: string;
+  }): Promise<ApiResponse<VerifyWebhookSchema>> {
+    const req = this.createRequest('POST', '/v1/notifications/verify-webhook-signature');
+    req.header('Content-Type', 'application/json');
+
+    req.throwOn(
+      400,
+      CustomError,
+      'Request is not well-formed, syntactically incorrect, or violates schema.',
+    );
+    req.throwOn(
+      401,
+      CustomError,
+      'Authentication failed due to missing authorization header, or invalid authentication credentials.',
+    );
+    req.throwOn(
+      422,
+      CustomError,
+      'The requested action could not be performed, semantically incorrect, or failed business validation.',
+    );
+    req.json(
+      Object.fromEntries(
+        Object.entries(body).map(([key, value]) => [
+          key.replace(/[A-Z]/g, letter => `_${letter.toLowerCase()}`),
+          value,
+        ]),
+      ),
+    );
+
+    req.authenticate([{ oauth2: true }]);
+    return req.callAsJson(verifyWebhookSchema);
+  }
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+import { validateRequiredKeys } from '@paykit-sdk/core';
+import { PayPalOptions, PayPalProvider } from './paypal-provider';
+
+export const paypal = () => {
+  const envVars = validateRequiredKeys(
+    ['PAYPAL_CLIENT_ID', 'PAYPAL_CLIENT_SECRET', 'PAYPAL_SANDBOX'],
+    process.env as Record<string, string>,
+    'Missing required environment variables: {keys}',
+  );
+
+  return new PayPalProvider({
+    clientId: envVars.PAYPAL_CLIENT_ID,
+    clientSecret: envVars.PAYPAL_CLIENT_SECRET,
+    isSandbox: envVars.PAYPAL_SANDBOX === 'true',
+  });
+};
+
+export const createPayPal = (config: PayPalOptions) => {
+  return new PayPalProvider(config);
+};

package/src/paypal-provider.ts

@@ -0,0 +1,504 @@
+import {
+  PayKitProvider,
+  Checkout,
+  CreateCheckoutSchema,
+  CreateCustomerParams,
+  Customer,
+  UpdateCustomerParams,
+  Subscription,
+  UpdateSubscriptionSchema,
+  paykitEvent$InboundSchema,
+  WebhookEventPayload,
+  PaykitProviderOptions,
+  HandleWebhookParams,
+  UpdateCheckoutSchema,
+  CreateSubscriptionSchema,
+  CreatePaymentSchema,
+  Payment,
+  UpdatePaymentSchema,
+  CreateRefundSchema,
+  Refund,
+  validateRequiredKeys,
+  ProviderNotSupportedError,
+  ConstraintViolationError,
+  ResourceNotFoundError,
+  WebhookError,
+  NotImplementedError,
+  schema,
+  AbstractPayKitProvider,
+} from '@paykit-sdk/core';
+import {
+  CheckoutPaymentIntent,
+  Client,
+  Environment,
+  LogLevel,
+  Order,
+  OrdersController,
+  PaymentsController,
+  Refund as PayPalRefund,
+  OrderApplicationContextUserAction,
+} from '@paypal/paypal-server-sdk';
+import { z } from 'zod';
+import { SubscriptionsController } from './controllers/subscription';
+import { WebhookController } from './controllers/webhook';
+import { VerifyWebhookStatus } from './schema';
+import {
+  paykitCheckout$InboundSchema,
+  paykitPayment$InboundSchema,
+  paykitRefund$InboundSchema,
+} from './utils/mapper';
+
+const PAYPAL_METADATA_MAX_LENGTH = 127;
+
+export interface PayPalOptions extends PaykitProviderOptions {
+  /**
+   * The client ID for the PayPal API
+   */
+  clientId: string;
+
+  /**
+   * The client secret for the PayPal API
+   */
+  clientSecret: string;
+
+  /**
+   * Whether to use the sandbox environment
+   */
+  isSandbox: boolean;
+}
+
+const paypalOptionsSchema = schema<PayPalOptions>()(
+  z.object({
+    clientId: z.string(),
+    clientSecret: z.string(),
+    isSandbox: z.boolean(),
+    debug: z.boolean().optional(),
+  }),
+);
+
+const providerName = 'paypal';
+export class PayPalProvider extends AbstractPayKitProvider implements PayKitProvider {
+  readonly providerName = providerName;
+
+  private client: Client;
+  private ordersController: OrdersController;
+  private paymentsController: PaymentsController;
+  private subscriptionsController: SubscriptionsController;
+  private webhookController: WebhookController;
+
+  constructor(config: PayPalOptions) {
+    super(paypalOptionsSchema, config, providerName);
+
+    const { clientId, clientSecret, isSandbox = true, debug } = config;
+
+    const environment = isSandbox ? Environment.Sandbox : Environment.Production;
+
+    this.client = new Client({
+      clientCredentialsAuthCredentials: {
+        oAuthClientId: clientId,
+        oAuthClientSecret: clientSecret,
+      },
+      timeout: 0,
+      environment,
+      logging: {
+        logLevel: debug ? LogLevel.Info : LogLevel.Error,
+        logRequest: { logBody: debug },
+        logResponse: { logHeaders: debug },
+      },
+    });
+
+    this.ordersController = new OrdersController(this.client);
+    this.paymentsController = new PaymentsController(this.client);
+    this.subscriptionsController = new SubscriptionsController(this.client);
+    this.webhookController = new WebhookController(this.client);
+  }
+
+  /**
+   * Checkout management
+   * In PayPal, Order IS the checkout
+   */
+  createCheckout = async (params: CreateCheckoutSchema): Promise<Checkout> => {
+    const stringifiedMetadata = JSON.stringify(params.metadata);
+
+    if (stringifiedMetadata.length > PAYPAL_METADATA_MAX_LENGTH) {
+      throw new ConstraintViolationError('Metadata exceeds maximum length', {
+        value: stringifiedMetadata.length,
+        limit: PAYPAL_METADATA_MAX_LENGTH,
+        provider: this.providerName,
+      });
+    }
+    const {
+      currency = 'USD',
+      amount = '0',
+      itemName = 'Untitled Item',
+    } = validateRequiredKeys(
+      ['currency', 'amount', 'itemName'],
+      params.provider_metadata as Record<string, string>,
+      'Missing required parameters: {keys}',
+    );
+
+    const orderOptionsBody: Parameters<OrdersController['createOrder']>[0]['body'] = {
+      intent: CheckoutPaymentIntent.Capture,
+      payer: {
+        ...(typeof params.customer === 'string' && { payerId: params.customer }),
+        ...(typeof params.customer === 'object' &&
+          'email' in params.customer && { emailAddress: params.customer.email }),
+      },
+      purchaseUnits: [
+        {
+          amount: { currencyCode: currency, value: amount },
+          customId: stringifiedMetadata,
+          items: [
+            {
+              sku: params.item_id,
+              quantity: params.quantity.toString(),
+              name: itemName,
+              unitAmount: { currencyCode: currency, value: amount },
+            },
+          ],
+        },
+      ],
+      applicationContext: { userAction: OrderApplicationContextUserAction.PayNow },
+      ...(params.provider_metadata && { ...params.provider_metadata }),
+    };
+
+    if (params.billing) {
+      orderOptionsBody.purchaseUnits[0].shipping = {
+        name: { fullName: params.billing.address.name },
+        address: {
+          addressLine1: params.billing.address.line1,
+          addressLine2: params.billing.address.line2,
+          adminArea1: params.billing.address.city,
+          adminArea2: params.billing.address.state,
+          postalCode: params.billing.address.postal_code,
+          countryCode: params.billing.address.country,
+        },
+        ...(params.billing.address.phone && {
+          phoneNumber: {
+            nationalNumber: params.billing.address.phone,
+            countryCode: params.billing.address.country,
+          },
+        }),
+      };
+    }
+
+    const order = await this.ordersController.createOrder({ body: orderOptionsBody });
+
+    return paykitCheckout$InboundSchema(order.result);
+  };
+
+  retrieveCheckout = async (id: string): Promise<Checkout> => {
+    const order = await this.ordersController.getOrder({ id });
+
+    return paykitCheckout$InboundSchema(order.result);
+  };
+
+  updateCheckout = async (
+    id: string,
+    params: UpdateCheckoutSchema,
+  ): Promise<Checkout> => {
+    throw new ProviderNotSupportedError('updateCheckout', this.providerName, {
+      reason:
+        'PayPal does not support updating orders. Cancel and create a new order instead.',
+    });
+  };
+
+  deleteCheckout = async (id: string): Promise<null> => {
+    throw new ProviderNotSupportedError('deleteCheckout', this.providerName, {
+      reason: 'PayPal orders cannot be deleted. They expire automatically.',
+    });
+  };
+
+  createCustomer = async (params: CreateCustomerParams): Promise<Customer> => {
+    throw new ProviderNotSupportedError('customer management', this.providerName, {
+      reason: 'PayPal does not have standalone customer entities.',
+      alternative: 'Use Payer information within orders or implement PayPal Vault API',
+    });
+  };
+
+  updateCustomer = async (
+    id: string,
+    params: UpdateCustomerParams,
+  ): Promise<Customer> => {
+    throw new ProviderNotSupportedError('updateCustomer', this.providerName, {
+      reason: 'PayPal does not support standalone customer management.',
+    });
+  };
+
+  deleteCustomer = async (id: string): Promise<null> => {
+    throw new ProviderNotSupportedError('deleteCustomer', this.providerName, {
+      reason: 'PayPal does not support standalone customer management.',
+    });
+  };
+
+  retrieveCustomer = async (id: string): Promise<Customer | null> => {
+    throw new ProviderNotSupportedError('retrieveCustomer', this.providerName, {
+      reason: 'PayPal does not support standalone customer management.',
+    });
+  };
+
+  /**
+   * Subscription management
+   * Would need PayPal Subscriptions API - different from Orders
+   */
+  createSubscription = async (
+    params: CreateSubscriptionSchema,
+  ): Promise<Subscription> => {
+    const subscription = await this.subscriptionsController.createSubscription({
+      body: params,
+    });
+    return subscription as unknown as Subscription;
+  };
+
+  cancelSubscription = async (id: string): Promise<Subscription> => {
+    const subscription = await this.subscriptionsController.cancelSubscription({
+      subscriptionId: id,
+      reason: 'Customer requested cancellation',
+    });
+
+    return subscription as unknown as Subscription;
+  };
+
+  updateSubscription = async (
+    id: string,
+    params: UpdateSubscriptionSchema,
+  ): Promise<Subscription> => {
+    const stringifiedMetadata = JSON.stringify(params.metadata);
+
+    if (stringifiedMetadata.length > PAYPAL_METADATA_MAX_LENGTH) {
+      throw new ConstraintViolationError('Metadata exceeds maximum length', {
+        value: stringifiedMetadata.length,
+        limit: PAYPAL_METADATA_MAX_LENGTH,
+        provider: this.providerName,
+      });
+    }
+    const subscription = await this.subscriptionsController.updateSubscription({
+      subscriptionId: id,
+      metadata: params.metadata ?? {},
+    });
+
+    return subscription as unknown as Subscription;
+  };
+
+  retrieveSubscription = async (id: string): Promise<Subscription> => {
+    const subscription = await this.subscriptionsController.retrieveSubscription({
+      subscriptionId: id,
+    });
+
+    return subscription as unknown as Subscription;
+  };
+
+  deleteSubscription = async (id: string): Promise<null> => {
+    throw new NotImplementedError('deleteSubscription', 'PayPal', {
+      futureSupport: false,
+    });
+  };
+
+  /**
+   * Payment management
+   * In PayPal, Order IS the payment
+   */
+  createPayment = async (params: CreatePaymentSchema): Promise<Payment> => {
+    const stringifiedMetadata = JSON.stringify(params.metadata);
+
+    if (stringifiedMetadata.length > PAYPAL_METADATA_MAX_LENGTH) {
+      throw new ConstraintViolationError('Metadata exceeds maximum length', {
+        value: stringifiedMetadata.length,
+        limit: PAYPAL_METADATA_MAX_LENGTH,
+        provider: this.providerName,
+      });
+    }
+
+    const orderOptionsBody: Parameters<OrdersController['createOrder']>[0]['body'] = {
+      intent: CheckoutPaymentIntent.Capture,
+      payer: {
+        ...(typeof params.customer === 'string' && { payerId: params.customer }),
+        ...(typeof params.customer === 'object' &&
+          'email' in params.customer && { emailAddress: params.customer.email }),
+      },
+      purchaseUnits: [
+        {
+          amount: { currencyCode: params.currency, value: params.amount.toString() },
+          customId: stringifiedMetadata,
+        },
+      ],
+    };
+
+    if (params.billing) {
+      orderOptionsBody.purchaseUnits[0].shipping = {
+        name: { fullName: params.billing.address.name },
+        address: {
+          addressLine1: params.billing.address.line1,
+          addressLine2: params.billing.address.line2,
+          adminArea1: params.billing.address.city,
+          adminArea2: params.billing.address.state,
+          postalCode: params.billing.address.postal_code,
+          countryCode: params.billing.address.country,
+        },
+        ...(params.billing.address.phone && {
+          phoneNumber: {
+            nationalNumber: params.billing.address.phone,
+            countryCode: params.billing.address.country,
+          },
+        }),
+      };
+    }
+
+    const order = await this.ordersController.createOrder({ body: orderOptionsBody });
+
+    return paykitPayment$InboundSchema(order.result);
+  };
+
+  updatePayment = async (id: string, params: UpdatePaymentSchema): Promise<Payment> => {
+    throw new ProviderNotSupportedError('updatePayment', this.providerName, {
+      reason: 'PayPal does not support updating orders.',
+    });
+  };
+
+  retrievePayment = async (id: string): Promise<Payment | null> => {
+    const order = await this.ordersController.getOrder({ id });
+
+    return paykitPayment$InboundSchema(order.result);
+  };
+
+  deletePayment = async (id: string): Promise<null> => {
+    throw new ProviderNotSupportedError('deletePayment', this.providerName, {
+      reason: 'PayPal orders cannot be deleted. They expire automatically.',
+    });
+  };
+
+  capturePayment = async (id: string): Promise<Payment> => {
+    const captured = await this.ordersController.captureOrder({ id });
+    return paykitPayment$InboundSchema(captured.result);
+  };
+
+  cancelPayment = async (id: string): Promise<Payment> => {
+    // PayPal doesn't have explicit cancel, but you can void authorizations
+    throw new ProviderNotSupportedError('cancelPayment', this.providerName, {
+      reason:
+        'PayPal order cancellation not directly supported. Orders expire automatically.',
+    });
+  };
+
+  /**
+   * Refund management
+   */
+  createRefund = async (params: CreateRefundSchema): Promise<Refund> => {
+    const order = await this.ordersController.getOrder({ id: params.payment_id });
+
+    const captureIds =
+      order.result.purchaseUnits?.[0]?.payments?.captures?.map(c => c.id!) || [];
+
+    if (captureIds.length === 0) {
+      throw new ResourceNotFoundError('Capture', params.payment_id, this.providerName);
+    }
+
+    const currencyCode = order.result.purchaseUnits?.[0]?.amount?.currencyCode || 'USD';
+    const amount = params.amount
+      ? params.amount.toString()
+      : order.result.purchaseUnits?.[0]?.amount?.value || '0';
+
+    const refund = await this.paymentsController.refundCapturedPayment({
+      captureId: captureIds[0],
+      body: { amount: { currencyCode, value: amount } },
+    });
+
+    return paykitRefund$InboundSchema(refund.result);
+  };
+
+  /**
+   * Webhook management
+   */
+  handleWebhook = async (
+    params: HandleWebhookParams,
+  ): Promise<Array<WebhookEventPayload>> => {
+    const { body, headers, webhookSecret: webhookId } = params;
+
+    const { result } = await this.webhookController.verifyWebhook({
+      authAlgo: headers.get('paypal-auth-algo') as string,
+      certUrl: headers.get('paypal-cert-url') as string,
+      transmissionId: headers.get('paypal-transmission-id') as string,
+      transmissionSig: headers.get('paypal-transmission-sig') as string,
+      transmissionTime: headers.get('paypal-transmission-time') as string,
+      webhookId,
+      webhookEvent: JSON.parse(body),
+    });
+
+    if (result.verification_status !== VerifyWebhookStatus.SUCCESS) {
+      throw new WebhookError('Webhook verification failed', {
+        provider: this.providerName,
+      });
+    }
+
+    const event = JSON.parse(body);
+    const eventType = event.event_type;
+
+    const webhookHandlers: Record<string, () => Promise<Array<WebhookEventPayload>>> = {
+      'CHECKOUT.ORDER.APPROVED': async () => {
+        const orderData = event.resource as Order;
+        const payment = paykitPayment$InboundSchema(orderData);
+
+        return [
+          paykitEvent$InboundSchema<Payment>({
+            type: 'payment.created',
+            created: Date.now() / 1000,
+            id: event.id,
+            data: payment,
+          }),
+        ];
+      },
+
+      'CHECKOUT.ORDER.COMPLETED': async () => {
+        const orderData = event.resource as Order;
+        const payment = paykitPayment$InboundSchema(orderData);
+
+        return [
+          paykitEvent$InboundSchema<Payment>({
+            type: 'payment.updated',
+            created: Date.now() / 1000,
+            id: event.id,
+            data: payment,
+          }),
+        ];
+      },
+
+      'PAYMENT.CAPTURE.COMPLETED': async () => {
+        const orderData = event.resource as Order;
+        const payment = paykitPayment$InboundSchema(orderData);
+
+        return [
+          paykitEvent$InboundSchema<Payment>({
+            type: 'payment.updated',
+            created: Date.now() / 1000,
+            id: event.id,
+            data: payment,
+          }),
+        ];
+      },
+
+      'PAYMENT.CAPTURE.REFUNDED': async () => {
+        const refundData = event.resource as PayPalRefund;
+        const refund = paykitRefund$InboundSchema(refundData);
+
+        return [
+          paykitEvent$InboundSchema<Refund>({
+            type: 'refund.created',
+            created: Date.now() / 1000,
+            id: event.id,
+            data: refund,
+          }),
+        ];
+      },
+    };
+
+    const handler = webhookHandlers[eventType];
+
+    if (!handler) {
+      throw new WebhookError(`Unhandled event type: ${eventType}`, {
+        provider: this.providerName,
+      });
+    }
+
+    return await handler();
+  };
+}

package/src/schema.ts

@@ -0,0 +1,230 @@
+import {
+  lazy,
+  object,
+  Schema,
+  number,
+  string,
+  stringEnum,
+  boolean,
+} from '@paypal/paypal-server-sdk/dist/types/schema';
+
+export interface ShippingAmount {
+  /**
+   * The currency code.
+   */
+  currency_code: string;
+
+  /**
+   * The value which might be an integer for currencies like JPY that are not typically fractional.
+   */
+  value: string;
+}
+
+export const shippingAmountSchema: Schema<ShippingAmount> = object({
+  currency_code: ['currency_code', string()],
+  value: ['value', string()],
+});
+
+export interface CreateSubscriptionSchema {
+  /**
+   * The ID of the plan, maps to `item_id` in the Paykit SDK.
+   */
+  plan_id: string;
+
+  /**
+   * The quantity of the plan.
+   */
+  quantity: number;
+
+  /**
+   * The custom ID of the subscription.
+   */
+  custom_id: string;
+
+  /**
+   * The start time of the subscription.
+   */
+  start_time: string;
+
+  /**
+   * The subscriber of the subscription.
+   */
+  subscriber: {
+    email_address: string;
+    name: { given_name: string; surname: string };
+    phone: { phone_number: string };
+  };
+}
+
+export const createSubscriptionApticSchema: Schema<CreateSubscriptionSchema> = object({
+  plan_id: ['plan_id', string()],
+  quantity: ['quantity', number()],
+  custom_id: ['custom_id', string()],
+  start_time: ['start_time', string()],
+  subscriber: [
+    'subscriber',
+    lazy(() =>
+      object({
+        email_address: ['email_address', string()],
+        name: [
+          'name',
+          lazy(() =>
+            object({
+              given_name: ['given_name', string()],
+              surname: ['surname', string()],
+            }),
+          ),
+        ],
+        phone: [
+          'phone',
+          lazy(() => object({ phone_number: ['phone_number', string()] })),
+        ],
+      }),
+    ),
+  ],
+});
+
+enum SubscriptionStatus {
+  APPROVAL_PENDING = 'APPROVAL_PENDING',
+  APPROVED = 'APPROVED',
+  ACTIVE = 'ACTIVE',
+  SUSPENDED = 'SUSPENDED',
+  CANCELLED = 'CANCELLED',
+  EXPIRED = 'EXPIRED',
+}
+
+export interface Subscription {
+  /**
+   * The ID of the subscription.
+   */
+  id: string;
+
+  /**
+   * The ID of the plan.
+   */
+  plan_id: string;
+
+  /**
+   * The quantity of the subscription.
+   */
+  quantity: number;
+
+  /**
+   * The status of the subscription.
+   */
+  status: SubscriptionStatus;
+
+  /**
+   * The time the status was updated.
+   */
+  status_update_time: string;
+
+  /**
+   * The note for the status change.
+   */
+  status_change_note: string;
+
+  /**
+   * The time the subscription started.
+   */
+  start_time: string;
+
+  /**
+   * The subscriber of the subscription.
+   */
+  subscriber: {
+    /**
+     * The email address of the subscriber.
+     */
+    email_address: string;
+
+    /**
+     * The name of the subscriber.
+     */
+    name: {
+      /**
+       * The given name of the subscriber.
+       */
+      given_name: string;
+      /**
+       * The surname of the subscriber.
+       */
+      surname: string;
+    };
+
+    /**
+     * The ID of the payer.
+     */
+    payer_id: string;
+  };
+
+  /**
+   * Whether the plan was overridden.
+   */
+  plan_overridden: boolean;
+
+  /**
+   * The custom ID of the subscription.
+   */
+  custom_id: string;
+}
+
+export const subscriptionApticSchema: Schema<Subscription> = object({
+  id: ['id', string()],
+  plan_id: ['plan_id', string()],
+  quantity: ['quantity', number()],
+  custom_id: ['custom_id', string()],
+  plan_overridden: ['plan_overridden', boolean()],
+  start_time: ['start_time', string()],
+  subscriber: [
+    'subscriber',
+    lazy(() =>
+      object({
+        email_address: ['email_address', string()],
+        name: [
+          'name',
+          lazy(() =>
+            object({
+              given_name: ['given_name', string()],
+              surname: ['surname', string()],
+            }),
+          ),
+        ],
+        payer_id: ['payer_id', string()],
+      }),
+    ),
+  ],
+  status: ['status', stringEnum(SubscriptionStatus)],
+  status_change_note: ['status_change_note', string()],
+  status_update_time: ['status_update_time', string()],
+});
+
+interface ResumeSubscriptionSchema {
+  /**
+   * The reason for resuming the subscription.
+   */
+  reason: string;
+}
+
+export const resumeSubscriptionApticSchemaRequest: Schema<ResumeSubscriptionSchema> =
+  object({
+    reason: ['reason', string()],
+  });
+
+// WEBHOOK
+
+export enum VerifyWebhookStatus {
+  SUCCESS = 'SUCCESS',
+  FAILURE = 'FAILURE',
+}
+
+export interface VerifyWebhookSchema {
+  /**
+   * The status of the verification.
+   */
+  verification_status: VerifyWebhookStatus;
+}
+
+export const verifyWebhookSchema: Schema<VerifyWebhookSchema> = object({
+  verification_status: ['verification_status', stringEnum(VerifyWebhookStatus)],
+});

package/src/types.ts

@@ -0,0 +1,126 @@
+export type SubscriptionStatus =
+  | 'APPROVAL_PENDING'
+  | 'APPROVED'
+  | 'ACTIVE'
+  | 'SUSPENDED'
+  | 'CANCELLED'
+  | 'EXPIRED';
+
+export interface PayPalSubscription {
+  /**
+   * The ID of the subscription.
+   */
+  id: string;
+
+  /**
+   * The ID of the plan.
+   */
+  plan_id: string;
+
+  /**
+   * The status of the subscription.
+   */
+  status: SubscriptionStatus;
+
+  /**
+   * The time the status was updated.
+   */
+  status_update_time?: string;
+
+  /**
+   * The time the subscription started.
+   */
+  start_time?: string;
+
+  /**
+   * The time the subscription was created.
+   */
+  create_time?: string;
+
+  /**
+   * The subscriber of the subscription.
+   */
+  subscriber?: {
+    /**
+     * The email of the subscriber.
+     */
+    email_address?: string;
+
+    /**
+     * The name of the subscriber.
+     */
+    name?: {
+      /**
+       * The given name of the subscriber.
+       */
+      given_name?: string;
+      /**
+       * The surname of the subscriber.
+       */
+      surname?: string;
+    };
+  };
+
+  /**
+   * The billing info of the subscription.
+   */
+  billing_info?: {
+    /**
+     * The outstanding balance of the subscription.
+     */
+    outstanding_balance?: {
+      /**
+       * The currency code of the outstanding balance.
+       */
+      currency_code?: string;
+      /**
+       * The value of the outstanding balance.
+       */
+      value?: string;
+    };
+    cycle_executions?: Array<{
+      /**
+       * The tenure type of the cycle execution.
+       */
+      tenure_type?: string;
+
+      /**
+       * The sequence of the cycle execution.
+       */
+      sequence?: number;
+
+      /**
+       * The number of cycles completed.
+       */
+      cycles_completed?: number;
+
+      /**
+       * The total number of cycles.
+       */
+      total_cycles?: number;
+    }>;
+  };
+
+  /**
+   * The links of the subscription.
+   */
+  links?: Array<{
+    /**
+     * The href of the link.
+     */
+    href?: string;
+    /**
+     * The rel of the link.
+     */
+    rel?: string;
+    /**
+     * The method of the link.
+     */
+    method?: string;
+  }>;
+
+  /**
+   * The custom ID of the subscription, i.e metadata
+   */
+  customId?: string;
+}

package/src/utils/mapper.ts

@@ -0,0 +1,111 @@
+import {
+  Checkout,
+  omitInternalMetadata,
+  Payment,
+  Refund,
+  Subscription,
+} from '@paykit-sdk/core';
+import { Order, Refund as PayPalRefund } from '@paypal/paypal-server-sdk';
+import { PayPalSubscription } from '../types';
+
+/**
+ * Refund
+ */
+export const paykitRefund$InboundSchema = (refund: PayPalRefund): Refund => {
+  return {
+    id: refund.id!,
+    amount: refund.amount?.value ? parseFloat(refund.amount.value) : 0,
+    currency: refund.amount?.currencyCode || 'USD',
+    metadata: refund.customId ? omitInternalMetadata(JSON.parse(refund.customId)) : {},
+    reason: refund.noteToPayer ?? null,
+  };
+};
+
+/**
+ * Checkout
+ */
+export const paykitCheckout$InboundSchema = (order: Order): Checkout => {
+  return {
+    id: order.id!,
+    payment_url: order.links?.find(l => l.rel === 'approve')?.href || '',
+    amount: parseFloat(order.purchaseUnits?.[0]?.amount?.value || '0'),
+    currency: order.purchaseUnits?.[0]?.amount?.currencyCode || 'USD',
+    customer: order.payer?.payerId
+      ? order.payer?.payerId
+      : { email: order.payer?.emailAddress ?? '' },
+    session_type: 'one_time',
+    products: [{ id: order.purchaseUnits?.[0]?.items?.[0]?.sku || '', quantity: 1 }],
+    metadata: order.purchaseUnits?.[0]?.customId
+      ? omitInternalMetadata(JSON.parse(order.purchaseUnits?.[0]?.customId))
+      : {},
+    subscription: null,
+  };
+};
+
+/**
+ * Payment
+ */
+export const paykitPayment$InboundSchema = (order: Order): Payment => {
+  const statusMap: Record<string, Payment['status']> = {
+    CREATED: 'pending',
+    SAVED: 'pending',
+    APPROVED: 'requires_capture',
+    VOIDED: 'canceled',
+    COMPLETED: 'succeeded',
+    PAYER_ACTION_REQUIRED: 'requires_action',
+  };
+
+  const status = statusMap[order.status ?? statusMap.CREATED];
+
+  return {
+    id: order.id!,
+    status,
+    amount: parseFloat(order.purchaseUnits?.[0]?.amount?.value || '0'),
+    currency: order.purchaseUnits?.[0]?.amount?.currencyCode || 'USD',
+    metadata: order.purchaseUnits?.[0]?.customId
+      ? omitInternalMetadata(JSON.parse(order.purchaseUnits?.[0]?.customId))
+      : {},
+    customer: order.payer?.payerId
+      ? order.payer?.payerId
+      : { email: order.payer?.emailAddress ?? '' },
+    item_id: order.purchaseUnits?.[0]?.items?.[0]?.sku || '',
+  };
+};
+
+/**
+ * Subscription
+ */
+export const paykitSubscription$InboundSchema = (
+  subscription: PayPalSubscription,
+): Subscription => {
+  const statusMap: Record<string, Subscription['status']> = {
+    APPROVAL_PENDING: 'pending',
+    APPROVED: 'active',
+    ACTIVE: 'active',
+    SUSPENDED: 'past_due',
+    CANCELLED: 'canceled',
+    EXPIRED: 'canceled',
+  };
+
+  const status = statusMap[subscription.status ?? statusMap.APPROVAL_PENDING];
+
+  return {
+    id: subscription.id,
+    customer: { email: subscription.subscriber?.email_address ?? '' },
+    status,
+    item_id: subscription.plan_id,
+    current_period_start: subscription.start_time
+      ? new Date(subscription.start_time)
+      : new Date(),
+    current_period_end: subscription.status_update_time
+      ? new Date(subscription.status_update_time)
+      : new Date(), // todo: Would need to calculate based on billing cycle
+    metadata: subscription.customId
+      ? omitInternalMetadata(JSON.parse(subscription.customId))
+      : {},
+    billing_interval: 'month',
+    amount: 0,
+    currency: 'USD',
+    custom_fields: null,
+  };
+};

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "declaration": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}