@a_jackie_z/fastify 1.1.3 → 1.1.4

package/README.md

@@ -398,6 +398,7 @@ Creates and configures a Fastify server instance with Zod support and optional p
 Starts the Fastify server. Handles errors and exits the process if the server fails to start.
 
 **Parameters:**
+
 - `fastify` - The Fastify server instance
 - `host` - The host to bind to (e.g., '0.0.0.0' or 'localhost')
 - `port` - The port number to listen on
@@ -408,6 +409,69 @@ const app = await createFastify()
 await runFastify(app, '0.0.0.0', 3000)
 ```
 
+## Fastify JWT Service
+
+A typed helper for issuing and verifying access/refresh tokens alongside the Fastify JWT plugin.
+
+**Options**
+- `accessTokenExpiry` (string) — required access token lifetime (e.g., `15m`)
+- `refreshTokenExpiry` (string) — required refresh token lifetime (e.g., `7d`)
+- `renewalThreshold` (string) — renew refresh tokens when `exp` is within this window
+- `accessTokenSchema` (ZodSchema) — optional, extends `baseAccessTokenPayloadSchema`
+- `refreshTokenSchema` (ZodSchema) — optional, extends `baseRefreshTokenPayloadSchema`
+
+**Basic usage**
+```typescript
+import {
+  createFastify,
+  FastifyJwtService,
+  baseAccessTokenPayloadSchema,
+  baseRefreshTokenPayloadSchema,
+} from '@a_jackie_z/fastify'
+import { z } from 'zod'
+
+const app = await createFastify({
+  jwt: { secret: 'your-secret', global: false },
+})
+
+const jwtService = new FastifyJwtService(app, {
+  accessTokenExpiry: '15m',
+  refreshTokenExpiry: '7d',
+  renewalThreshold: '1d',
+})
+
+const { accessToken, refreshToken } = jwtService.generateTokenPair('identity-123')
+
+const accessPayload = jwtService.verifyAccessToken(accessToken)
+const refreshPayload = jwtService.verifyRefreshToken(refreshToken)
+
+if (jwtService.shouldRenewRefreshToken(refreshPayload.exp)) {
+  const renewedRefreshToken = jwtService.renewRefreshToken(refreshPayload.identityId)
+}
+```
+
+**Custom payloads**
+```typescript
+const accessTokenSchema = baseAccessTokenPayloadSchema.extend({
+  roles: z.array(z.string()),
+})
+
+const refreshTokenSchema = baseRefreshTokenPayloadSchema.extend({
+  deviceId: z.string().optional(),
+})
+
+const jwtService = new FastifyJwtService<
+  z.infer<typeof accessTokenSchema>,
+  z.infer<typeof refreshTokenSchema>
+>(app, {
+  accessTokenExpiry: '15m',
+  refreshTokenExpiry: '7d',
+  renewalThreshold: '1d',
+  accessTokenSchema,
+  refreshTokenSchema,
+})
+```
+
 ## Usage Patterns
 
 ### Pattern 1: Global JWT with Selective Public Routes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a_jackie_z/fastify",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "A collection of Fastify plugins and utilities for building robust web applications.",
   "license": "MIT",
   "author": "Sang Lu <connect.with.sang@gmail.com>",