feat(docs): Add docs on payment integrations

admin-ui/src/app/common/generated-types.ts

@@ -547,7 +547,11 @@ export type CreateZoneInput = {
   memberIds?: Maybe<Array<Scalars['ID']>>,
 };
 
-/** ISO 4217 currency code */
+/** @description
+ * ISO 4217 currency code
+ * 
+ * @docsCategory common
+ */
 export enum CurrencyCode {
   /** United Arab Emirates dirham */
   AED = 'AED',
@@ -1224,7 +1228,11 @@ export enum JobState {
 }
 
 
-/** ISO 639-1 language code */
+/** @description
+ * ISO 639-1 language code
+ * 
+ * @docsCategory common
+ */
 export enum LanguageCode {
   /** Afar */
   aa = 'aa',
@@ -2319,11 +2327,17 @@ export type PaymentMethodSortParameter = {
   code?: Maybe<SortOrder>,
 };
 
-/**  Permissions for administrators and customers  */
+/** "
+ * @description
+ * Permissions for administrators and customers. Used to control access to
+ * GraphQL resolvers via the {@link Allow} decorator.
+ * 
+ * @docsCategory common
+ */
 export enum Permission {
   /**  The Authenticated role means simply that the user is logged in  */
   Authenticated = 'Authenticated',
-  /**  SuperAdmin can perform the most sensitive tasks  */
+  /**  SuperAdmin can perform the most sensitive tasks */
   SuperAdmin = 'SuperAdmin',
   /**  Owner means the user owns this entity, e.g. a Customer's own Order */
   Owner = 'Owner',

docs/content/docs/developer-guide/payment-integrations.md

@@ -0,0 +1,45 @@
+---
+title: "Payment Integrations"
+showtoc: true
+---
+
+# Payment Integrations
+
+Vendure can support many kinds of payment workflows, such as authorizing and capturing payment in a single step upon checkout or authorizing on checkout and then capturing on fulfillment. 
+
+## Creating an integration
+
+Payment integrations are created by creating a new [PaymentMethodHandler]({{< relref "payment-method-handler" >}}) and passing that handler into the [`paymentOptions.paymentMethodHandlers`]({{< relref "payment-options" >}}) array in the VendureConfig.
+
+```TypeScript
+import { PaymentMethodHandler, VendureConfig } from '@vendure/core';
+
+const myPaymentIntegration = new PaymentMethodHandler({
+    code: 'my-payment-method',
+    // ... 
+    // configuration of the handler (see PaymentMethodConfigOptions docs)
+});
+
+export const config: VendureConfig = {
+    // ...
+    paymentOptions: {
+        paymentMethodHandlers: [myPaymentIntegration],
+    },
+};
+```
+
+For a more complete example of a payment integration, see the [PaymentMethodHandler]({{< relref "payment-method-handler" >}}) documentation.
+
+## Using an integration
+
+In you storefront application, this payment method can then be used when executing the [`addPaymentToOrder` mutation]({{< relref "/docs/graphql-api/shop/mutations#addpaymenttoorder" >}}), as the "method" field of the [`PaymentInput` object]({{< relref "/docs/graphql-api/shop/input-types#paymentinput" >}}).
+
+```SDL
+mutation {
+    addPaymentToOrder(input: { 
+        method: "my-payment-method",
+        metadata: { id: "<some id from the payment provider>" }) {
+        ...Order
+    }
+}
+```

packages/common/src/generated-shop-types.ts

@@ -1581,8 +1581,14 @@ export type Payment = Node & {
     metadata?: Maybe<Scalars['JSON']>;
 };
 
+/** Passed as input to the `addPaymentToOrder` mutation. */
 export type PaymentInput = {
+    /** This field should correspond to the `code` property of a PaymentMethodHandler. */
     method: Scalars['String'];
+    /** This field should contain arbitrary data passed to the specified PaymentMethodHandler's `createPayment()` method
+     * as the "metadata" argument. For example, it could contain an ID for the payment and other
+     * data generated by the payment provider.
+     */
     metadata: Scalars['JSON'];
 };
 

packages/core/e2e/graphql/generated-e2e-shop-types.ts

@@ -1581,8 +1581,14 @@ export type Payment = Node & {
     metadata?: Maybe<Scalars['JSON']>;
 };
 
+/** Passed as input to the `addPaymentToOrder` mutation. */
 export type PaymentInput = {
+    /** This field should correspond to the `code` property of a PaymentMethodHandler. */
     method: Scalars['String'];
+    /** This field should contain arbitrary data passed to the specified PaymentMethodHandler's `createPayment()` method
+     * as the "metadata" argument. For example, it could contain an ID for the payment and other
+     * data generated by the payment provider.
+     */
     metadata: Scalars['JSON'];
 };
 

packages/core/src/api/schema/shop-api/shop.api.graphql

@@ -78,8 +78,19 @@ input UpdateCustomerInput {
     phoneNumber: String
 }
 
+"""
+Passed as input to the `addPaymentToOrder` mutation.
+"""
 input PaymentInput {
+    """
+    This field should correspond to the `code` property of a PaymentMethodHandler.
+    """
     method: String!
+    """
+    This field should contain arbitrary data passed to the specified PaymentMethodHandler's `createPayment()` method
+    as the "metadata" argument. For example, it could contain an ID for the payment and other
+    data generated by the payment provider.
+    """
     metadata: JSON!
 }
 

packages/core/src/config/payment-method/payment-method-handler.ts

@@ -213,7 +213,10 @@ export interface PaymentMethodConfigOptions<T extends PaymentMethodArgs = Paymen
  *
  * export const examplePaymentHandler = new PaymentMethodHandler({
  *     code: 'example-payment-provider',
- *     description: 'Example Payment Provider',
+ *     description: [{
+ *         languageCode: LanguageCode.en,
+ *         value: 'Example Payment Provider',
+ *     }],
  *     args: {
  *         apiKey: { type: 'string' },
  *     },

packages/email-plugin/src/event-listener.ts

@@ -37,6 +37,14 @@ export interface EmailTemplateConfig {
     subject: string;
 }
 
+/**
+ * @description
+ * A function used to define template variables available to email templates.
+ * See {@link EmailEventHandler}.setTemplateVars().
+ *
+ * @docsCategory EmailPlugin
+ * @docsPage Email Plugin Types
+ */
 export type SetTemplateVarsFn<Event> = (
     event: Event,
     globals: { [key: string]: any },
@@ -113,10 +121,12 @@ export class EmailEventHandler<T extends string = string, Event extends EventWit
 
     constructor(public listener: EmailEventListener<T>, public event: Type<Event>) {}
 
+    /** @internal */
     get type(): T {
         return this.listener.type;
     }
 
+    /** @internal */
     get mockEvent(): Omit<Event, 'ctx'> | undefined {
         return this._mockEvent;
     }

packages/email-plugin/src/types.ts

@@ -12,16 +12,17 @@ import { EmailEventHandler } from './event-listener';
  * to use when generating the email.
  *
  * @docsCategory EmailPlugin
+ * @docsPage Email Plugin Types
  */
-export type EventWithContext = VendureEvent & { ctx: RequestContext; };
+export type EventWithContext = VendureEvent & { ctx: RequestContext };
 
 /**
  * @description
  * Configuration for the EmailPlugin.
  *
  * @docsCategory EmailPlugin
- * @docsWeight 0
- */
+ * @docsPage EmailPluginOptions
+ * */
 export interface EmailPluginOptions {
     /**
      * @description
@@ -46,7 +47,7 @@ export interface EmailPluginOptions {
      * the storefront URL could be defined here and then used in the "email address verification"
      * email.
      */
-    globalTemplateVars?: { [key: string]: any; };
+    globalTemplateVars?: { [key: string]: any };
 }
 
 /**
@@ -54,6 +55,7 @@ export interface EmailPluginOptions {
  * Configuration for running the EmailPlugin in development mode.
  *
  * @docsCategory EmailPlugin
+ * @docsPage EmailPluginOptions
  */
 export interface EmailPluginDevModeOptions extends Omit<EmailPluginOptions, 'transport'> {
     devMode: true;
@@ -71,18 +73,40 @@ export interface EmailPluginDevModeOptions extends Omit<EmailPluginOptions, 'tra
     mailboxPort?: number;
 }
 
+/**
+ * @description
+ * The credentials used for sending email via SMTP
+ *
+ * @docsCategory EmailPlugin
+ * @docsPage Email Plugin Types
+ */
 export interface SMTPCredentials {
-    /** the username */
+    /** @description The username */
     user: string;
-    /** then password */
+    /** @description The password */
     pass: string;
 }
 
+/**
+ * @description
+ * A union of all the possible transport options for sending emails.
+ *
+ * @docsCategory EmailPlugin
+ * @docsPage Transport Options
+ */
+export type EmailTransportOptions =
+    | SMTPTransportOptions
+    | SendmailTransportOptions
+    | FileTransportOptions
+    | NoopTransportOptions
+    | TestingTransportOptions;
+
 /**
  * @description
  * A subset of the SMTP transport options of [Nodemailer](https://nodemailer.com/smtp/)
  *
  * @docsCategory EmailPlugin
+ * @docsPage Transport Options
  */
 export interface SMTPTransportOptions {
     type: 'smtp';
@@ -138,6 +162,7 @@ export interface SMTPTransportOptions {
  * Uses the local Sendmail program to send the email.
  *
  * @docsCategory EmailPlugin
+ * @docsPage Transport Options
  */
 export interface SendmailTransportOptions {
     type: 'sendmail';
@@ -152,6 +177,7 @@ export interface SendmailTransportOptions {
  * Outputs the email as an HTML file for development purposes.
  *
  * @docsCategory EmailPlugin
+ * @docsPage Transport Options
  */
 export interface FileTransportOptions {
     type: 'file';
@@ -166,13 +192,18 @@ export interface FileTransportOptions {
  * Does nothing with the generated email. Mainly intended for use in testing where we don't care about the email transport.
  *
  * @docsCategory EmailPlugin
+ * @docsPage Transport Options
  */
 export interface NoopTransportOptions {
     type: 'none';
 }
 
 /**
+ * @description
  * The final, generated email details to be sent.
+ *
+ * @docsCategory EmailPlugin
+ * @docsPage Email Plugin Types
  */
 export interface EmailDetails {
     recipient: string;
@@ -185,6 +216,7 @@ export interface EmailDetails {
  * Forwards the raw GeneratedEmailContext object to a provided callback, for use in testing.
  *
  * @docsCategory EmailPlugin
+ * @docsPage Transport Options
  */
 export interface TestingTransportOptions {
     type: 'testing';
@@ -195,19 +227,6 @@ export interface TestingTransportOptions {
     onSend: (details: EmailDetails) => void;
 }
 
-/**
- * @description
- * A union of all the possible transport options for sending emails.
- *
- * @docsCategory EmailPlugin
- */
-export type EmailTransportOptions =
-    | SMTPTransportOptions
-    | SendmailTransportOptions
-    | FileTransportOptions
-    | NoopTransportOptions
-    | TestingTransportOptions;
-
 /**
  * @description
  * An EmailGenerator generates the subject and body details of an email.
@@ -227,6 +246,6 @@ export interface EmailGenerator<T extends string = any, E extends VendureEvent =
     generate(
         subject: string,
         body: string,
-        templateVars: { [key: string]: any; },
+        templateVars: { [key: string]: any },
     ): Omit<EmailDetails, 'recipient'>;
 }