Update docs

Author: fpseverino

Diff for: Sources/FluentWallet/Models/Concrete Models/Device.swift

@@ -24,6 +24,7 @@ final public class Device: DeviceModel, @unchecked Sendable {
     public init() {}
 }
 
+/// The migration that creates the ``Device`` table.
 public struct CreateDevice: AsyncMigration {
     public func prepare(on database: any Database) async throws {
         try await database.schema(Device.FieldKeys.schemaName)

Diff for: Sources/FluentWallet/Models/Concrete Models/LogEntry.swift

@@ -19,6 +19,7 @@ final public class LogEntry: LogEntryModel, @unchecked Sendable {
     public init() {}
 }
 
+/// The migration that creates the ``LogEntry`` table.
 public struct CreateLogEntry: AsyncMigration {
     public func prepare(on database: any Database) async throws {
         try await database.schema(LogEntry.FieldKeys.schemaName)

Diff for: Sources/FluentWalletOrders/Models/Concrete Models/Order.swift

@@ -37,6 +37,7 @@ final public class Order: OrderModel, @unchecked Sendable {
     }
 }
 
+/// The migration that creates the ``Order`` table.
 public struct CreateOrder: AsyncMigration {
     public func prepare(on database: any Database) async throws {
         try await database.schema(Order.FieldKeys.schemaName)

Diff for: Sources/FluentWalletOrders/Models/Concrete Models/OrdersRegistration.swift

@@ -20,6 +20,7 @@ final public class OrdersRegistration: OrdersRegistrationModel, @unchecked Senda
     public init() {}
 }
 
+/// The migration that creates the ``OrdersRegistration`` table.
 public struct CreateOrdersRegistration: AsyncMigration {
     public func prepare(on database: any Database) async throws {
         try await database.schema(OrdersRegistration.FieldKeys.schemaName)

Diff for: Sources/FluentWalletPasses/FluentWalletPasses.docc/FluentWalletPasses.md

@@ -13,16 +13,20 @@ This package provides a collection of Fluent protocol and concrete models, usefu
 - ``PassDataModel``
 - ``PassModel``
 - ``PassesRegistrationModel``
-- ``PersonalizationModel``
 
 ### Concrete Models
 
 - ``Pass``
 - ``PassesRegistration``
-- ``Personalization``
 
 ### Migrations
 
 - ``CreatePass``
 - ``CreatePassesRegistration``
+
+### Personalized Passes
+
+- <doc:PersonalizedPasses>
+- ``PersonalizationModel``
+- ``Personalization``
 - ``CreatePersonalization``

Diff for: Sources/FluentWalletPasses/FluentWalletPasses.docc/PersonalizedPasses.md

@@ -0,0 +1,88 @@
+# Setting Up Pass Personalization
+
+Create a personalized pass for Apple Wallet.
+
+## Overview
+
+> Warning: This section is a work in progress. Testing is hard without access to the certificates required to develop this feature. If you have access to the entitlements, please help us implement this feature.
+
+Pass Personalization lets you create passes, referred to as personalizable passes, that prompt the user to provide personal information during signup that is used to update the pass.
+
+> Important: Making a pass personalizable, just like adding NFC to a pass, requires a special entitlement issued by Apple. Although accessing such entitlements is hard if you're not a big company, you can learn more in [Getting Started with Apple Wallet](https://developer.apple.com/wallet/get-started/).
+
+Personalizable passes can be distributed like any other pass. For information on personalizable passes, see the [Wallet Developer Guide](https://developer.apple.com/library/archive/documentation/UserExperience/Conceptual/PassKit_PG/PassPersonalization.html#//apple_ref/doc/uid/TP40012195-CH12-SW2) and [Return a Personalized Pass](https://developer.apple.com/documentation/walletpasses/return_a_personalized_pass).
+
+### Implement the Data Model
+
+You'll have to make a few changes to your ``PassDataModel`` to support personalizable passes.
+
+A personalizable pass is just a standard pass package with the following additional files:
+
+- A `personalization.json` file.
+- A `[email protected]` file.
+
+Implement the ``PassDataModel/personalizationJSON(on:)`` method.
+If the pass requires personalization, and if it was not already personalized, create the `PersonalizationJSON` struct, which will contain all the fields for the generated `personalization.json` file, and return it, otherwise return `nil`.
+
+In the ``PassDataModel/sourceFilesDirectoryPath(on:)`` method, you have to return two different directory paths, depending on whether the pass has to be personalized or not. If it does, the directory must contain the `[email protected]` file.
+
+Finally, you have to implement the ``PassDataModel/passJSON(on:)`` method as usual, but remember to use in the `PassJSON.Properties` initializer the user info that will be saved inside ``Personalization`` after the pass has been personalized.
+Each ``Personalization`` instance has a reference to the pass it belongs to, so you can easily retrieve the user info for the pass.
+
+```swift
+extension PassData {
+    func passJSON(on db: any Database) async throws -> any PassJSON.Properties {
+        // Here create the pass JSON data as usual.
+        try await PassJSONData(data: self, pass: self.$pass.get(on: db))
+    }
+
+    func personalizationJSON(on db: any Database) async throws -> PersonalizationJSON? {
+        let pass = try await self.$pass.get(on: db)
+
+        let personalization = try await Personalization.query(on: db)
+            .filter(\.$pass.$id == pass.requireID())
+            .first()
+
+        if personalization == nil {
+            // If the pass requires personalization, create the personalization JSON struct.
+            return PersonalizationJSON(
+                requiredPersonalizationFields: [.name, .postalCode, .emailAddress, .phoneNumber],
+                description: "Hello, World!"
+            )
+        } else {
+            // Otherwise, return `nil`.
+            return nil
+        }
+    }
+
+    func sourceFilesDirectoryPath(on db: any Database) async throws -> String {
+        if self.requiresPersonalization {
+            // If the pass requires personalization, return the URL path to the personalization template,
+            // which must contain the `[email protected]` file.
+            return "SourceFiles/Passes/Personalization/"
+        } else {
+            // Otherwise, return the URL path to the standard pass template.
+            return "SourceFiles/Passes/Standard/"
+        }
+    }
+}
+```
+
+### Implement the Web Service
+
+After implementing the data model methods, there is nothing else you have to do.
+
+Build the pass bundle with a `PassBuilder` as usual and distribute it.
+The user will be prompted to provide the required personal information when they add the pass.
+Wallet will then send the user personal information to your server, which should be saved in the ``Personalization`` table.
+Immediately after that, Wallet will request the updated pass.
+This updated pass will contain the user personalization data that was previously saved inside the ``Personalization`` table.
+You can access the pass linked to the personalization data by using the ``Personalization/pass`` field.
+
+> Important: This updated and personalized pass **must not** contain the `personalization.json` file, so make sure that the ``PassDataModel/personalizationJSON(on:)`` method returns `nil` when the pass has already been personalized.
+
+## Topics
+
+### Data Model Method
+
+- ``PassDataModel/personalizationJSON(on:)``

Diff for: Sources/FluentWalletPasses/Models/Concrete Models/Pass.swift

@@ -35,6 +35,7 @@ final public class Pass: PassModel, @unchecked Sendable {
     }
 }
 
+/// The migration that creates the ``Pass`` table.
 public struct CreatePass: AsyncMigration {
     public func prepare(on database: any Database) async throws {
         try await database.schema(Pass.FieldKeys.schemaName)

Diff for: Sources/FluentWalletPasses/Models/Concrete Models/PassesRegistration.swift

@@ -20,6 +20,7 @@ final public class PassesRegistration: PassesRegistrationModel, @unchecked Senda
     public init() {}
 }
 
+/// The migration that creates the ``PassesRegistration`` table.
 public struct CreatePassesRegistration: AsyncMigration {
     public func prepare(on database: any Database) async throws {
         try await database.schema(PassesRegistration.FieldKeys.schemaName)

Diff for: Sources/FluentWalletPasses/Models/Concrete Models/Personalization.swift

@@ -50,6 +50,7 @@ final public class Personalization: PersonalizationModel, @unchecked Sendable {
     public init() {}
 }
 
+/// The migration that creates the ``Personalization`` table.
 public struct CreatePersonalization: AsyncMigration {
     public func prepare(on database: any Database) async throws {
         try await database.schema(Personalization.FieldKeys.schemaName)