### Install fastify-passkit-webservice

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/blob/main/packages/fastify/README.md

Install the package using npm.

```sh
$ npm install fastify-passkit-webservice
```

--------------------------------

### Install hono-passkit-webservice

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/blob/main/packages/hono/README.md

Install the package using npm.

```sh
npm install hono-passkit-webservice
```

--------------------------------

### Install Passkit WebService Toolkit

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/blob/main/packages/toolkit/README.md

Install the package using npm. This is the initial step to integrate the toolkit into your project.

```sh
npm install passkit-webservice-toolkit
```

--------------------------------

### Install intent-passkit-webservice

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/blob/main/packages/intent/README.md

Install the package using npm. This command adds the necessary dependencies to your project.

```sh
$ npm install intent-passkit-webservice
```

--------------------------------

### Install adonis-passkit-webservice

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/blob/main/packages/adonis/README.md

Install the package using npm.

```sh
npm install adonis-passkit-webservice
```

--------------------------------

### Install express-passkit-webservice

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/blob/main/packages/express/README.md

Install the package using npm.

```sh
npm install express-passkit-webservice
```

--------------------------------

### Basic Hono Registration Router Setup

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/blob/main/packages/hono/README.md

Set up the registration router for Apple Wallet pass registration and unregistration. Implement the onRegister and onUnregister callbacks to handle device and pass information.

```js
import { Hono } from "hono";
import registrationRouter from "hono-passkit-webservice/v1/registration.js";

const app = new Hono();

app.route("/", registrationRouter({
	async onRegister(deviceLibraryIdentifier, passTypeIdentifier, serialNumber, pushToken) {
		/** your implementation */
	}
	async onUnregister(deviceLibraryIdentifier, passTypeIdentifier, serialNumber) {
		/** your implementation */
	}
}));
```

--------------------------------

### Register Passkit WebService Plugin

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/blob/main/packages/fastify/README.md

Example of registering the fastify-passkit-webservice plugin for handling registration and unregistration events. Implement your business logic within the provided async functions.

```js
import Fastify from "fastify";

const app = Fastify();

app.register(import("fastify-passkit-webservice/v1/registration.js"), {
	async onRegister(
		deviceLibraryIdentifier,
		passTypeIdentifier,
		serialNumber,
		pushToken,
	) {
		/** your implementation */
	},
	async onUnregister(
		deviceLibraryIdentifier,
		passTypeIdentifier,
		serialNumber,
	) {
		/** your implementation */
	},
	async tokenVerifier(token) {
		/** your implementation */
	},
});
```

--------------------------------

### Using Custom Prefix for Registration Router

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Hono.dev-Documentation

Demonstrates how to use a custom prefix for the registration router and the importance of updating pass.json.

```javascript
import registrationRouter from "hono-passkit-webservice/v1/registration.js";

app.use("/apple/wallet/", registrationRouter({
   ...middlewareOpts
}));
```

--------------------------------

### Registering a Plugin with Fastify

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Fastify-Documentation

Shows how to register a specific plugin, such as the registration plugin, with a Fastify instance, including passing plugin options.

```javascript
fastifyInstance.register(import("fastify-passkit-webservice/v1/registration.js"), {
   ...pluginOpts
});
```

--------------------------------

### Importing from Passkit Webservice Toolkit (CJS)

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Toolkit-documentation

Demonstrates how to import modules from the toolkit using CommonJS (CJS) syntax.

```javascript
const { v1 } = require("passkit-webservice-toolkit");
const { ... } = require("passkit-webservice-toolkit/v1");
const { LogEndpoint } = require("passkit-webservice-toolkit/v1/log.js");
```

--------------------------------

### Importing Hono Passkit Middlewares

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Hono.dev-Documentation

Demonstrates various ways to import middlewares from the hono-passkit-webservice package.

```javascript
import { v1 } from "hono-passkit-webservice";
import { ... } from "hono-passkit-webservice/v1";
import logRouter from "hono-passkit-webservice/v1/log.js";
```

--------------------------------

### Importing Fastify Passkit Plugins

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Fastify-Documentation

Demonstrates various ways to import plugins from the fastify-passkit-webservice package, including direct and versioned imports.

```javascript
import { v1 } from "fastify-passkit-webservice";
import { ... } from "fastify-passkit-webservice/v1";
import logPlugin from "fastify-passkit-webservice/v1/log.js";
```

--------------------------------

### Adding Registration Router Directly

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Hono.dev-Documentation

Shows how to add the registration router to a Hono instance using dynamic import.

```javascript
app.route("/", (await import("hono-passkit-webservice/v1/registration.js").default({
   ...middlewareOpts
}));
```

--------------------------------

### Importing from Passkit Webservice Toolkit (ESM)

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Toolkit-documentation

Demonstrates how to import modules from the toolkit using ECMAScript Modules (ESM) syntax.

```javascript
import { v1 } from "passkit-webservice-toolkit";
import { ... } from "passkit-webservice-toolkit/v1";
import { LogEndpoint } from "passkit-webservice-toolkit/v1/log.js";
```

--------------------------------

### Custom Prefix for Registration Middleware

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Express.js-Documentation

Demonstrates how to use a custom prefix for the registration middleware and the importance of updating the pass.json webServiceURL.

```javascript
import registrationRouter from "express-passkit-webservice/v1/registration.js";

app.use("/apple/wallet/", registrationRouter({
   ...middlewareOpts
}));
```

--------------------------------

### Package Entry Points

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Fastify-Documentation

Defines the available entry points for the package in package.json, allowing for different import strategies.

```json
{
	".": "./lib/index.js",
	"./v1": "./lib/plugins/v1/index.js",
	"./v1/*": "./lib/plugins/v1/*"
}
```

--------------------------------

### Importing Express PassKit Middlewares

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Express.js-Documentation

Demonstrates various ways to import middlewares from the express-passkit-webservice package, supporting ESM.

```javascript
import { v1 } from "express-passkit-webservice";
```

```javascript
import { ... } from "express-passkit-webservice/v1";
```

```javascript
import logRouter from "express-passkit-webservice/v1/log.js";
```

--------------------------------

### Package Entry Points Configuration

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Toolkit-documentation

Specifies the import and require paths for different service versions within the package.json file, enabling compatibility with both CJS and ESM.

```json
{
	".": {
		"import": "./lib/esm/index.js",
		"require": "./lib/cjs/index.js"
	},
	"./v1": {
		"import": "./lib/esm/services/v1/index.js",
		"require": "./lib/cjs/services/v1/index.js"
	},
	"./v1/*": {
		"import": "./lib/esm/services/v1/*",
		"require": "./lib/cjs/services/v1/*"
	}
}
```

--------------------------------

### Adding Registration Router with Named Import

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Hono.dev-Documentation

Illustrates adding the registration router to a Hono instance using a named import.

```javascript
import registrationRouter from "hono-passkit-webservice/v1/registration.js";

app.route("/", registrationRouter({
   ...middlwareOpts
}));
```

--------------------------------

### Adding Registration Middleware Directly

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Express.js-Documentation

Shows how to add the registration middleware to an Express app using dynamic import.

```javascript
app.use((await import("express-passkit-webservice/v1/registration.js").default({
   ...middlewareOpts
})));
```

--------------------------------

### Package Entry Points

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Toolkit-documentation

Details the available entry points for the passkit-webservice-toolkit package in its package.json, specifying import paths for both CJS and ESM module systems.

```APIDOC
## Package Entry Points

### Description
The `passkit-webservice-toolkit` package is designed for compatibility with both CommonJS (CJS) and ECMAScript Modules (ESM). The `package.json` file defines specific entry points for different import strategies.

### CJS and ESM Imports

```json
{
	".": {
		"import": "./lib/esm/index.js",
		"require": "./lib/cjs/index.js"
	},
	"./v1": {
		"import": "./lib/esm/services/v1/index.js",
		"require": "./lib/cjs/services/v1/index.js"
	},
	"./v1/*": {
		"import": "./lib/esm/services/v1/*",
		"require": "./lib/cjs/services/v1/*"
	}
}
```

### Usage Examples

**ESM:**
```js
import { v1 } from "passkit-webservice-toolkit";
import { ... } from "passkit-webservice-toolkit/v1";
import { LogEndpoint } from "passkit-webservice-toolkit/v1/log.js";
```

**CJS:**
```js
const { v1 } = require("passkit-webservice-toolkit");
const { ... } = require("passkit-webservice-toolkit/v1");
const { LogEndpoint } = require("passkit-webservice-toolkit/v1/log.js");
```
```

--------------------------------

### Package Entry Points

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Hono.dev-Documentation

Defines the available entry points for the hono-passkit-webservice package in package.json.

```json
{
	".": "./lib/index.js",
	"./v1": "./lib/middlewares/v1/index.js",
	"./v1/*": "./lib/middlewares/v1/*"
}
```

--------------------------------

### Integrating with NestJS

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Fastify-Documentation

Illustrates how to register a fastify-passkit-webservice plugin within a NestJS application's bootstrap function, including handling potential Fastify version conflicts.

```typescript
/** src/main.ts **/

import LogPlugin from "fastify-passkit-webservice/v1/log.js";

async function bootstrap() {
	const app = await NestFactory.create<NestFastifyApplication>(
		AppModule,
		new FastifyAdapter(),
	);

	app.register(
		// @ts-ignore
		LogPlugin,
		{
			onIncomingLogs(logs) {
				/** Your implementation **/
			}
		},
	);

	await app.listen(process.env.PORT ?? 3000);
}
```

--------------------------------

### Adding Registration Middleware with Named Import

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Express.js-Documentation

Illustrates adding the registration middleware to an Express app using a named import.

```javascript
import registrationRouter from "express-passkit-webservice/v1/registration.js";

app.use(registrationRouter({
   ...middlwareOpts
}));
```

--------------------------------

### Integrating Registration Middleware with NestJS

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Express.js-Documentation

Shows how to integrate the registration middleware into a NestJS application's bootstrap function, including custom callbacks and token verification.

```typescript
/** src/main.ts **/

async function bootstrap() {
	const app = await NestFactory.create(AppModule);

	app.use(
		"/pass", /** Custom prefix, if desired **/
		(await import("express-passkit-webservice/v1/registration.js")).default({
			await onRegister(
				deviceLibraryIdentifier,
				passTypeIdentifier,
				serialNumber,
				pushToken,
			) {
				/** Your implementation **/
			},
			await onUnregister(
				deviceLibraryIdentifier,
				passTypeIdentifier,
				serialNumber,
			) {
				/** Your implementation **/
			},
			await tokenVerifier(token) {
				console.log("Verifying token", token);
				return true;
			},
		}),
	);

	await app.listen(process.env.PORT ?? 3000);
}
```

--------------------------------

### Registration Plugin

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Fastify-Documentation

This plugin handles both device registration and unregistration endpoints for Apple Wallet. It requires mandatory callbacks for registration and unregistration, and optionally accepts a token verifier for validating Apple-sent tokens.

```APIDOC
## Registration Plugin

### Description
This plugin wraps both device registration and unregistration endpoints as they are coupled.

### Entrypoint
`fastify-passkit-webservice/v1/registration.js`

### Callbacks
#### `onRegister` (mandatory)
```typescript
onRegister(deviceLibraryIdentifier: string, passTypeIdentifier: string, serialNumber: string, pushToken: string): PromiseLike<boolean>;
```

#### `onUnregister` (mandatory)
```typescript
onUnregister(deviceLibraryIdentifier: string, passTypeIdentifier: string, serialNumber: string): PromiseLike<boolean>;
```

#### `tokenVerifier` (optional)
Can be used to verify the token sent by Apple Wallet and that is available in a pass. If set, this function is called before both `onRegister` and `onUnregister`.
```typescript
tokenVerifier?(token: string): PromiseLike<boolean>;
```
```

--------------------------------

### Registration Middleware

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Express.js-Documentation

This middleware handles both device registration and unregistration endpoints, which are coupled according to Apple's specifications. It requires mandatory callbacks for registration and unregistration, and optionally accepts a token verifier.

```APIDOC
## Registration Middleware

### Description
This middleware wraps both device registration and unregistration endpoints as they are coupled. It requires mandatory callbacks for `onRegister` and `onUnregister`, and optionally accepts a `tokenVerifier`.

### Entrypoint
`express-passkit-webservice/v1/registration.js`

### Middleware Callbacks

#### `onRegister` (mandatory)
```typescript
onRegister(deviceLibraryIdentifier: string, passTypeIdentifier: string, serialNumber: string, pushToken: string): PromiseLike<boolean>;
```

#### `onUnregister` (mandatory)
```typescript
onUnregister(deviceLibraryIdentifier: string, passTypeIdentifier: string, serialNumber: string): PromiseLike<boolean>;
```

#### `tokenVerifier` (optional)
This function is called before `onRegister` and `onUnregister` to verify the token sent by Apple Wallet. If not provided, no token verification is performed by the middleware.
```typescript
tokenVerifier?(token: string): PromiseLike<boolean>;
```

### Example Usage (Express)
```javascript
import registrationRouter from "express-passkit-webservice/v1/registration.js";

app.use(registrationRouter({
   async onRegister(deviceLibraryIdentifier, passTypeIdentifier, serialNumber, pushToken) {
      // Your implementation to handle registration
      console.log('Registering:', deviceLibraryIdentifier, passTypeIdentifier, serialNumber, pushToken);
      return true;
   },
   async onUnregister(deviceLibraryIdentifier, passTypeIdentifier, serialNumber) {
      // Your implementation to handle unregistration
      console.log('Unregistering:', deviceLibraryIdentifier, passTypeIdentifier, serialNumber);
      return true;
   },
   async tokenVerifier(token) {
      // Your implementation to verify the token
      console.log('Verifying token:', token);
      return true; // or false if verification fails
   }
}));
```

### Example Usage (NestJS)
```typescript
/** src/main.ts **/
async function bootstrap() {
	const app = await NestFactory.create(AppModule);

	app.use(
		"/pass", // Custom prefix, if desired
		(await import("express-passkit-webservice/v1/registration.js")).default({
			async onRegister(deviceLibraryIdentifier, passTypeIdentifier, serialNumber, pushToken) {
				/** Your implementation **/
			},
			await onUnregister(deviceLibraryIdentifier, passTypeIdentifier, serialNumber) {
				/** Your implementation **/
			},
			await tokenVerifier(token) {
				console.log("Verifying token", token);
				return true;
			},
		}),
	);

	await app.listen(process.env.PORT ?? 3000);
}
```
```

--------------------------------

### Express Passkit WebService Registration Middleware

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/blob/main/packages/express/README.md

Use the registration router middleware to handle device registration and unregistration events. Implement the onRegister and onUnregister async functions to define your business logic for these events.

```js
import express from "express";
import registrationRouter from "express-passkit-webservice/v1/registration.js";

const app = express();

app.use(registrationRouter({
	async onRegister(deviceLibraryIdentifier, passTypeIdentifier, serialNumber, pushToken) {
		/** your implementation */
	}
	async onUnregister(deviceLibraryIdentifier, passTypeIdentifier, serialNumber) {
		/** your implementation */
	}
}));
```

--------------------------------

### Define Entrypoint Structure

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Toolkit-documentation

Defines the structure for an entrypoint, including HTTP method, path, and parameters. This type helps in understanding the exact values for endpoint properties.

```typescript
type EntrypointDefinition = {
    method: "POST";
    path: "/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber";
    params: ["deviceLibraryIdentifier", "passTypeIdentifier", "serialNumber"];
    toString(): "POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber";
}
```

--------------------------------

### Registering Controller in HttpKernel

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/blob/main/packages/intent/README.md

Register the RegistrationController within your HttpKernel. This makes the controller's routes available in your application.

```js
/** Registering Controller inside: app/http/kernel.ts **/
/** Use require or import as a CJS TS */
const { v1: { Registration: { Controller: RegistrationController }} } = require("intent-passkit-webservice");

export class HttpKernel extends Kernel {
	public controllers(): Type<any>[] {
		return [
			RegistrationController,
		];
	}

	// ...
```

--------------------------------

### Log Plugin

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Fastify-Documentation

Handles incoming log messages from Apple Wallet, which may contain records about failed requests.

```APIDOC
## Log Plugin

### Description
This plugin wraps the request Apple will perform in case of logs. Logs may contain records about failed requests (e.g. missing endpoints or bad status code).

### Callbacks

- `onIncomingLogs` (_mandatory_): Handles incoming log messages.
  ```ts
  onIncomingLogs(logs: string[]): void;
  ```
```

--------------------------------

### Registration Plugin Callbacks

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Fastify-Documentation

Defines the mandatory and optional callbacks for the registration plugin, including onRegister, onUnregister, and tokenVerifier.

```typescript
declare function registrationPlugin(...);
export default registrationPlugin;
```

```typescript
onRegister(deviceLibraryIdentifier: string, passTypeIdentifier: string, serialNumber: string, pushToken: string): PromiseLike<boolean>;
```

```typescript
onUnregister(deviceLibraryIdentifier: string, passTypeIdentifier: string, serialNumber: string): PromiseLike<boolean>;
```

```typescript
tokenVerifier?(token: string): PromiseLike<boolean>;
```

--------------------------------

### Log Middleware

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Hono.dev-Documentation

Handles log requests from Apple, which may contain records about failed requests. It requires an `onIncomingLogs` callback to process the received log data.

```APIDOC
## Log

### Description
This middleware wraps the request Apple will perform in case of logs. Logs may contain records about failed requests (e.g. missing endpoints or bad status code).

### Entrypoint
`hono-passkit-webservice/v1/log.js`

### Default Export
`LogRouter`

### Middleware Callbacks

- `onIncomingLogs` (_mandatory_)
  - Processes the incoming logs.
  - Signature: `(logs: string[]): void`
```

--------------------------------

### List Plugin

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Fastify-Documentation

Handles requests from Apple Wallet for a list of updatable passes. It requires an `onListRetrieve` callback to fetch serial numbers updated since a given timestamp.

```APIDOC
## List Plugin

### Description
This plugin wraps the request for changed passes that Apple Wallet sends after receiving an APNS notification. After the list of updated serial numbers is provided, Apple Wallet will use that information to perform a request per serial number to your `update` plugin.

### Callbacks

- `onListRetrieve` (_mandatory_): This endpoint is called with two parameters and a query string: `passesUpdatedSince`. This value is the value you sent in the previous `list` request (won't be provided on the first request).
  ```ts
  onListRetrieve(deviceLibraryIdentifier: string, passTypeIdentifier: string, filters: {
	passesUpdatedSince?: LastUpdatedFormat
}): PromiseLike<SerialNumbers | undefined>;
  ```
```

--------------------------------

### Registering Service with IntentJS

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/IntentJS-Documentation

Register the RegistrationService within your application's ServiceProvider. You must implement the provided callbacks for onRegister, onUnregister, and tokenVerifier.

```typescript
/** Registering Service inside: app/boot/sp/app.ts **/
/** Use require or import as a CJS TS */
const { v1: { Registration: { Service: RegistrationService }} } = require("intent-passkit-webservice");

export class AppServiceProvider extends ServiceProvider {
	/**
	 * Register any application services here.
	 */
	register() {
		this.bindWithValue(RegistrationService, {
			await onRegister(
				deviceLibraryIdentifier: string,
				passTypeIdentifier: string,
				serialNumber: string,
				pushToken: string,
			): Promise<boolean> {
				/** your implementation */
			},
			await onUnregister(
				deviceLibraryIdentifier: string,
				passTypeIdentifier: string,
				serialNumber: string,
			): Promise<void> {
				/** your implementation */
			},
			await tokenVerifier(token: string): Promise<boolean> {
				/** your implementation */
			},
		});
	}

	// ...
```

--------------------------------

### Registering Service in AppServiceProvider

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/blob/main/packages/intent/README.md

Register the RegistrationService within your AppServiceProvider. This involves providing implementations for onRegister, onUnregister, and tokenVerifier methods.

```js
/** Registering Service inside: app/boot/sp/app.ts **/
/** Use require or import as a CJS TS */
const { v1: { Registration: { Service: RegistrationService }} } = require("intent-passkit-webservice");

export class AppServiceProvider extends ServiceProvider {
	/**
	 * Register any application services here.
	 */
	register() {
		this.bindWithValue(RegistrationService, {
			async onRegister(
				deviceLibraryIdentifier: string,
				passTypeIdentifier: string,
				serialNumber: string,
				pushToken: string,
			): Promise<boolean> {
				/** your implementation */
			},
			await async onUnregister(
				deviceLibraryIdentifier: string,
				passTypeIdentifier: string,
				serialNumber: string,
			): Promise<void> {
				/** your implementation */
			},
			await async tokenVerifier(token: string): Promise<boolean> {
				/** your implementation */
			},
		});
	}

	// ...
```

--------------------------------

### Registration Router Callbacks

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Hono.dev-Documentation

Defines the mandatory and optional callbacks for the RegistrationRouter, including onRegister, onUnregister, and tokenVerifier.

```typescript
declare function RegistrationRouter(...);
export default RegistrationRouter;
```

```typescript
onRegister(deviceLibraryIdentifier: string, passTypeIdentifier: string, serialNumber: string, pushToken: string): PromiseLike<boolean>;
```

```typescript
onUnregister(deviceLibraryIdentifier: string, passTypeIdentifier: string, serialNumber: string): PromiseLike<boolean>;
```

```typescript
tokenVerifier?(token: string): PromiseLike<boolean>;
```

--------------------------------

### Express PassKit Registration Middleware Configuration

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Express.js-Documentation

Defines the structure and callbacks for the RegistrationRouter middleware, including mandatory onRegister and onUnregister, and optional tokenVerifier.

```typescript
declare function RegistrationRouter(...);
export default RegistrationRouter;
```

--------------------------------

### Register Device for Pass Updates

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/IntentJS-Documentation

Callback for registering a device to receive pass update notifications. Requires device and pass identifiers, and a push token.

```typescript
onRegister(deviceLibraryIdentifier: string, passTypeIdentifier: string, serialNumber: string, pushToken: string): PromiseLike<boolean>;
```

--------------------------------

### List Middleware

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Hono.dev-Documentation

Wraps requests from Apple Wallet for a list of updated passes. This is typically invoked after an APNS notification and requires an `onListRetrieve` callback to provide serial numbers of updated passes.

```APIDOC
## List

### Description
This middleware wraps the request for changed passes that Apple Wallet sends after receiving an APNS notification. After the list of updated serial numbers is provided, Apple Wallet will use that information to perform a request per serial number to your `update` middleware.

### Entrypoint
`hono-passkit-webservice/v1/list.js`

### Default Export
`ListRouter<LastUpdatedFormat = unknown>`

### Middleware Callbacks

- `onListRetrieve` (_mandatory_)
  - Called with `deviceLibraryIdentifier`, `passTypeIdentifier`, and `filters` including `passesUpdatedSince`. The format of `passesUpdatedSince` is flexible and can be specified via `LastUpdatedFormat`.
  - Signature: `(deviceLibraryIdentifier: string, passTypeIdentifier: string, filters: { passesUpdatedSince?: LastUpdatedFormat }): PromiseLike<SerialNumbers | undefined>`
```

--------------------------------

### EntrypointDefinition Type

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Toolkit-documentation

Defines the structure for an endpoint, including its HTTP method, path, and parameters. This allows for type-safe endpoint construction and provides details via hover information in Typescript.

```APIDOC
## EntrypointDefinition Type

### Description
This Typescript type defines the structure for an endpoint definition within the PassKit Webservice Toolkit. It includes the HTTP method, the endpoint path with placeholders, and a list of parameters.

### Type Definition
```typescript
type EntrypointDefinition = {
    method: "POST";
    path: "/v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber";
    params: ["deviceLibraryIdentifier", "passTypeIdentifier", "serialNumber"];
    toString(): "POST /v1/devices/:deviceLibraryIdentifier/registrations/:passTypeIdentifier/:serialNumber";
}
```
```

--------------------------------

### Log Endpoint

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Toolkit-documentation

Allows logging a message. It exports ListEndpoint and ListParams, and defines LogEntries as the request body.

```APIDOC
## POST /passkit-webservice-toolkit/v1/log.js

### Description
Logs a message.

### Method
POST

### Endpoint
/passkit-webservice-toolkit/v1/log.js

### Parameters
#### Request Body
- **LogEntries** (interface) - Required - The request body defined by Apple.
- **ListParams** (type) - Required - Type shortcut to (typeof LogEndpoint)["params"]
```

--------------------------------

### AdonisJS Route Registration for Passkit

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/blob/main/packages/adonis/README.md

Configure routes in AdonisJS to handle Apple Wallet registration and unregistration events. Implement the onRegister, onUnregister, and tokenVerifier callbacks to integrate your business logic.

```typescript
/** src/start/routes.ts */
import router from "@adonisjs/core/services/router";

router.group(
	(await import("adonis-passkit-webservice/v1/registration.js")).default({
		async onRegister(
			deviceLibraryIdentifier,
			passTypeIdentifier,
			serialNumber,
			pushToken,
		) {
			/** Your implementation */
		},
		async onUnregister(
			deviceLibraryIdentifier,
			passTypeIdentifier,
			serialNumber,
		) {
			/** Your implementation */
		},
		async tokenVerifier(token) {
			/** Your implementation */
			return true;
		},
	}),
);
```

--------------------------------

### Fastify List Plugin Declaration

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Fastify-Documentation

Declares the list plugin for Fastify. This plugin handles requests from Apple Wallet for lists of updated passes.

```typescript
declare function listPlugin<LastUpdatedFormat = unknown>(...);
export default listPlugin;
```

--------------------------------

### Registration Router

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Hono.dev-Documentation

This middleware handles both device registration and unregistration endpoints for Apple Wallet passes. It requires mandatory callbacks for registration and unregistration, and optionally accepts a token verifier.

```APIDOC
## Registration Router

### Description
This middleware wraps both device registration and unregistration endpoints as they are coupled.

### Entrypoint
`hono-passkit-webservice/v1/registration.js`

### Default exports
`RegistrationRouter`

```ts
declare function RegistrationRouter(...);
export default RegistrationRouter;
```

### Middleware callbacks

- `onRegister` (_mandatory_)

```ts
onRegister(deviceLibraryIdentifier: string, passTypeIdentifier: string, serialNumber: string, pushToken: string): PromiseLike<boolean>;
```

- `onUnregister` (_mandatory_)

```ts
onUnregister(deviceLibraryIdentifier: string, passTypeIdentifier: string, serialNumber: string): PromiseLike<boolean>;
```

- `tokenVerifier` (_optional_)

Can be used to verify the token sent by Apple Wallet and that is available in a pass. If set, this function is called before both `onRegister` and `onUnregister`.

```ts
tokenVerifier?(token: string): PromiseLike<boolean>;
```
```

--------------------------------

### Implement onUpdateRequest Callback

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Hono.dev-Documentation

The mandatory onUpdateRequest callback is used to generate a pass when requested by Apple Wallet. Returning undefined results in a 304 Not Modified response, while returning anything else (except Uint8Array) results in a 500 Internal Server Error.

```typescript
onUpdateRequest(passTypeIdentifier: string, serialNumber: string): PromiseLike<Uint8Array>;
```

--------------------------------

### Implement onUpdateRequest Callback

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Express.js-Documentation

Defines the onUpdateRequest callback for the UpdateRouter. This function is mandatory and should generate the pass. Returning undefined results in a 304 Not Modified response, while other return types determine the success or failure status code.

```typescript
onUpdateRequest(passTypeIdentifier: string, serialNumber: string): PromiseLike<Uint8Array | undefined>;
```

--------------------------------

### Update Plugin

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Fastify-Documentation

Handles requests from Apple Wallet to update passes. It requires an `onUpdateRequest` callback to generate the pass data. An optional `tokenVerifier` can be provided to validate tokens.

```APIDOC
## Update Plugin

### Description
This plugin wraps the request for a Pass update made by Apple Wallet on two occasions: Manual refresh by the user, or refresh by application following an APNS notification.

### Callbacks

- `onUpdateRequest` (_mandatory_): Generate your pass when this callback is received. Returning `undefined` will result in an `HTTP 304`. Returning anything else except `Uint8Array` will result in an `HTTP 500`.
  ```ts
  onUpdateRequest(passTypeIdentifier: string, serialNumber: string): PromiseLike<Uint8Array>;
  ```

- `tokenVerifier` (_optional_): Can be used to verify the token sent by Apple Wallet. If set, this function is called before `onUpdateRequest`.
  ```ts
  tokenVerifier?(token: string): PromiseLike<boolean>;
  ```
```

--------------------------------

### Implement onIncomingLogs Callback

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Hono.dev-Documentation

The mandatory onIncomingLogs callback is used to process log messages received from Apple. This function should handle the array of log strings.

```typescript
onIncomingLogs(logs: string[]): void;
```

--------------------------------

### Implement tokenVerifier Callback

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Hono.dev-Documentation

The optional tokenVerifier callback can be used to verify the token sent by Apple Wallet. If implemented, it is called before the onUpdateRequest callback.

```typescript
tokenVerifier?(token: string): PromiseLike<boolean>;
```

--------------------------------

### List Middleware

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Express.js-Documentation

Wraps requests from Apple Wallet to retrieve a list of updated passes. This is typically called after an APNS notification is received, and it provides Apple Wallet with serial numbers that need to be updated. The `onListRetrieve` callback handles the retrieval logic, accepting device and pass identifiers, and an optional `passesUpdatedSince` filter.

```APIDOC
## List

### Description
This middleware handles requests from Apple Wallet to get a list of updated passes. After receiving an APNS notification, Apple Wallet uses this endpoint to fetch serial numbers that require updating. The `onListRetrieve` callback is mandatory for this middleware.

### Method
POST (Implicit, as it's a middleware wrapping a request)

### Endpoint
`/v1/list` (Implicit)

### Middleware Callbacks
#### `onListRetrieve` (mandatory)
This callback is invoked with `deviceLibraryIdentifier`, `passTypeIdentifier`, and an optional `filters` object containing `passesUpdatedSince`. It should return a `PromiseLike<SerialNumbers | undefined>`.

```ts
onListRetrieve(deviceLibraryIdentifier: string, passTypeIdentifier: string, filters: {
	passesUpdatedSince?: LastUpdatedFormat
}): PromiseLike<SerialNumbers | undefined>;
```

**Note**: `LastUpdatedFormat` is generic and defaults to `unknown`, allowing flexibility in handling the `passesUpdatedSince` parameter.
```

--------------------------------

### Register Endpoint

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Toolkit-documentation

Allows for registering a pass for update notifications from Apple. It exports RegisterEndpoint and RegisterParams, and handles PushToken as a request body.

```APIDOC
## POST /passkit-webservice-toolkit/v1/register.js

### Description
Registers a pass for update notifications.

### Method
POST

### Endpoint
/passkit-webservice-toolkit/v1/register.js

### Parameters
#### Request Body
- **PushToken** (interface) - Required - The request body from Apple.
```

--------------------------------

### Registration Service

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/IntentJS-Documentation

Handles device registration and unregistration for pass update notifications. It includes optional token verification.

```APIDOC
## Registration

### Description
Wraps both device registration and unregistration endpoints.

### Service Callbacks

- `onRegister` (mandatory)
  - Signature: `onRegister(deviceLibraryIdentifier: string, passTypeIdentifier: string, serialNumber: string, pushToken: string): PromiseLike<boolean>`
  - Description: Registers a device for pass update notifications.

- `onUnregister` (mandatory)
  - Signature: `onUnregister(deviceLibraryIdentifier: string, passTypeIdentifier: string, serialNumber: string): PromiseLike<boolean>`
  - Description: Unregisters a device for pass update notifications.

- `tokenVerifier` (optional)
  - Signature: `tokenVerifier?(token: string): PromiseLike<boolean>`
  - Description: Verifies the token sent by Apple Wallet.
```

--------------------------------

### Fastify Log Plugin Declaration

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Fastify-Documentation

Declares the log plugin for Fastify. This plugin handles incoming log messages from Apple.

```typescript
declare function logPlugin(...);
export default logPlugin;
```

--------------------------------

### Extending a Controller with Custom Path

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/IntentJS-Documentation

Extend a provided controller to customize the base path for its routes. Ensure all controllers are extended if you override one, and always provide the service dependency.

```typescript
const { v1: { List } } = require("intent-passkit-webservice");
const { Controller } = require("@intentjs/core");

@Controller("/pass")
export default class ExtendedListController extends List.Controller {
	constructor(service: List.Service) {
		super(service);
	}
}
```

--------------------------------

### List Service

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/IntentJS-Documentation

Handles requests for changed passes that Apple Wallet sends after receiving an APNS notification.

```APIDOC
## List

### Description
Wraps the request for changed passes that Apple Wallet sends after receiving an APNS notification.

### Service Callbacks

- `onListRetrieve` (mandatory)
  - Signature: `onListRetrieve(deviceLibraryIdentifier: string, passTypeIdentifier: string, filters: { passesUpdatedSince?: LastUpdatedFormat }): PromiseLike<SerialNumbers | undefined>`
  - Description: Called with `passesUpdatedSince` query parameter. The `LastUpdatedFormat` is `unknown` and can be specified or casted.
```

--------------------------------

### Update Middleware

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Hono.dev-Documentation

Handles requests from Apple Wallet for pass updates, triggered by manual refresh or APNS notifications. It requires an `onUpdateRequest` callback to generate the pass and optionally accepts a `tokenVerifier` for token validation.

```APIDOC
## Update

### Description
This middleware wraps the request for a Pass update made by Apple Wallet on two occasions: Manual refresh by the user, or refresh by application following an APNS notification.

### Entrypoint
`hono-passkit-webservice/v1/update.js`

### Default Export
`UpdateRouter`

### Middleware Callbacks

- `onUpdateRequest` (_mandatory_)
  - Generates the pass. Returning `undefined` results in `HTTP 304`. Returning anything else except `Uint8Array` results in `HTTP 500`.
  - Signature: `(passTypeIdentifier: string, serialNumber: string): PromiseLike<Uint8Array>`

- `tokenVerifier` (_optional_)
  - Verifies the token sent by Apple Wallet. If set, this function is called before `onUpdateRequest`.
  - Signature: `(token: string): PromiseLike<boolean>`
```

--------------------------------

### Declare UpdateRouter Middleware

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Hono.dev-Documentation

Declares the UpdateRouter middleware function. This is the default export for handling pass update requests from Apple Wallet.

```typescript
declare function UpdateRouter(...);
export default UpdateRouter;
```

--------------------------------

### Fastify Update Plugin Declaration

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Fastify-Documentation

Declares the update plugin for Fastify. This plugin handles requests from Apple Wallet for pass updates.

```typescript
declare function updatePlugin(...);
export default updatePlugin;
```

--------------------------------

### Log Service

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/IntentJS-Documentation

Handles log messages sent by Apple, which may contain records about failed requests.

```APIDOC
## Log

### Description
Wraps the request Apple will perform in case of logs.

### Service Callbacks

- `onIncomingLogs` (mandatory)
  - Signature: `onIncomingLogs(logs: string[]): void`
  - Description: Receives an array of log messages.
```

--------------------------------

### Declare ListRouter Middleware

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Hono.dev-Documentation

Declares the ListRouter middleware function. This is the default export for handling requests for lists of updatable passes from Apple Wallet.

```typescript
declare function ListRouter<LastUpdatedFormat = unknown>(...);
export default ListRouter;
```

--------------------------------

### List Endpoint

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Toolkit-documentation

Retrieves the list of updatable passes. This is called after the server signals Apple of updates. It exports ListEndpoint and ListParams, and defines SerialNumbers as the response body.

```APIDOC
## POST /passkit-webservice-toolkit/v1/list.js

### Description
Gets the list of updatable passes. Called after the server signals Apple of updates via APNS.

### Method
POST

### Endpoint
/passkit-webservice-toolkit/v1/list.js

### Parameters
#### Request Body
- **ListParams** (type) - Required - Type shortcut to (typeof ListEndpoint)["params"]

### Response
#### Success Response (200)
- **SerialNumbers** (interface) - Description - The response body to send back to Apple.
```

--------------------------------

### Declare LogRouter Middleware

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Hono.dev-Documentation

Declares the LogRouter middleware function. This is the default export for handling log messages sent by Apple.

```typescript
declare function LogRouter(...);
export default LogRouter;
```

--------------------------------

### Update Middleware

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Express.js-Documentation

Handles requests from Apple Wallet for updated passes. This middleware is invoked during manual refreshes or application-initiated refreshes following an APNS notification. It allows for custom pass generation and defines behavior for HTTP responses (304, 200, 500) based on the return value of the `onUpdateRequest` callback.

```APIDOC
## Update

### Description
This middleware handles requests from Apple Wallet for updated passes. It is invoked when a user manually refreshes their pass or when an application initiates a refresh after receiving an APNS notification.

### Method
POST (Implicit, as it's a middleware wrapping a request)

### Endpoint
`/v1/update` (Implicit)

### Middleware Callbacks
#### `onUpdateRequest` (mandatory)
This callback is responsible for generating the pass. It receives `passTypeIdentifier` and `serialNumber` as arguments and should return a `PromiseLike<Uint8Array | undefined>`.
- Returning `undefined` results in an `HTTP 304` response.
- Returning `Uint8Array` or any other value (except `undefined`) results in an `HTTP 200` response.
- Returning anything other than `undefined` or `Uint8Array` results in an `HTTP 500` response.

```ts
onUpdateRequest(passTypeIdentifier: string, serialNumber: string): PromiseLike<Uint8Array | undefined>;
```

#### `tokenVerifier` (optional)
This callback is used to verify the token sent by Apple Wallet. If provided, it is called before `onUpdateRequest`.

```ts
tokenVerifier?(token: string): PromiseLike<boolean>;
```
```

--------------------------------

### getAuthorizationToken

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Toolkit-documentation

Extracts the token from a provided Authorization header string. It performs basic validation on the Authorization schema.

```APIDOC
## getAuthorizationToken

### Description

Extracts the token from the Authorization header you provide. Performs a light validation on the Authorization Schema.

**Throws** if the schema is not `ApplePass`.

### Signature

```ts
declare function getAuthorizationToken(authorizationString: string): string;
```

### Parameters

#### Path Parameters

* None

#### Query Parameters

* None

#### Request Body

* None

### Request Example

* None

### Response

* **string**: The extracted authorization token.

### Response Example

* None

### Error Handling

* Throws an error if the authorization schema is not `ApplePass`.
```

--------------------------------

### Extract Authorization Token

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Toolkit-documentation

Extracts the token from the provided Authorization header. Performs a light validation on the Authorization Schema. Throws an error if the schema is not 'ApplePass'.

```typescript
declare function getAuthorizationToken(authorizationString: string): string;
```

--------------------------------

### Update Endpoint

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Toolkit-documentation

Enables sending an updated pass. It exports UpdateEndpoint and UpdateParams.

```APIDOC
## POST /passkit-webservice-toolkit/v1/update.js

### Description
Sends an updated pass.

### Method
POST

### Endpoint
/passkit-webservice-toolkit/v1/update.js

### Parameters
#### Request Body
- **UpdateParams** (type) - Required - Type shortcut to (typeof UpdateEndpoint)["params"]
```

--------------------------------

### Validate Authorization Scheme

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Toolkit-documentation

Performs light validation on the Authorization schema to check if it is 'ApplePass'. Returns a boolean indicating validity.

```typescript
declare function isAuthorizationSchemeValid(authorizationString: string): boolean;
```

--------------------------------

### Update Service

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/IntentJS-Documentation

Handles requests for pass updates initiated by Apple Wallet, either through manual refresh or APNS notifications.

```APIDOC
## Update

### Description
Wraps the request for a Pass update made by Apple Wallet.

### Service Callbacks

- `onUpdateRequest` (mandatory)
  - Signature: `onUpdateRequest(passTypeIdentifier: string, serialNumber: string): PromiseLike<Uint8Array>`
  - Description: Generates the pass when this callback is received. Returning `undefined` results in HTTP 304, otherwise HTTP 200. Returning other types results in HTTP 500.

- `tokenVerifier` (optional)
  - Signature: `tokenVerifier?(token: string): PromiseLike<boolean>`
  - Description: Verifies the token sent by Apple Wallet.
```

--------------------------------

### Implement onListRetrieve Callback

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Hono.dev-Documentation

The mandatory onListRetrieve callback is called with deviceLibraryIdentifier, passTypeIdentifier, and an optional filters object containing passesUpdatedSince. This function should return a list of serial numbers for updated passes.

```typescript
onListRetrieve(deviceLibraryIdentifier: string, passTypeIdentifier: string, filters: {
	passesUpdatedSince?: LastUpdatedFormat
}): PromiseLike<SerialNumbers | undefined>;
```

--------------------------------

### Unregister Device from Pass Updates

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/IntentJS-Documentation

Callback for unregistering a device from receiving pass update notifications. Requires device and pass identifiers.

```typescript
onUnregister(deviceLibraryIdentifier: string, passTypeIdentifier: string, serialNumber: string): PromiseLike<boolean>;
```

--------------------------------

### Unregister Endpoint

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Toolkit-documentation

Provides functionality to unregister a pass for update notifications. It exports UnregisterEndpoint and UnregisterParams.

```APIDOC
## POST /passkit-webservice-toolkit/v1/unregister.js

### Description
Unregisters a pass for update notifications.

### Method
POST

### Endpoint
/passkit-webservice-toolkit/v1/unregister.js

### Parameters
#### Request Body
- **UnregisterParams** (type) - Required - Type shortcut to (typeof UnregisterEndpoint)["params"]
```

--------------------------------

### isAuthorizationSchemeValid

Source: https://github.com/alexandercerutti/passkit-webservice-toolkit/wiki/Toolkit-documentation

Validates the Authorization header's scheme. It checks if the scheme is 'ApplePass' and returns a boolean indicating validity.

```APIDOC
## isAuthorizationSchemeValid

### Description

Performs light validation on the Authorization schema, by checking if it is `ApplePass` and returning the right `boolean`.

### Signature

```ts
declare function isAuthorizationSchemeValid(authorizationString: string): boolean;
```

### Parameters

#### Path Parameters

* None

#### Query Parameters

* None

#### Request Body

* None

### Request Example

* None

### Response

* **boolean**: `true` if the authorization scheme is valid (e.g., 'ApplePass'), `false` otherwise.

### Response Example

* None
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.