https://github.com/inyourtime/fastify-line
A Fastify plugin for the LINE Messaging API
https://github.com/inyourtime/fastify-line
bot fastify fastify-plugin line line-bot sdk
Last synced: 5 months ago
JSON representation
A Fastify plugin for the LINE Messaging API
- Host: GitHub
- URL: https://github.com/inyourtime/fastify-line
- Owner: inyourtime
- License: mit
- Created: 2025-07-01T12:47:21.000Z (12 months ago)
- Default Branch: main
- Last Pushed: 2025-07-13T05:54:20.000Z (11 months ago)
- Last Synced: 2025-07-13T05:59:30.151Z (11 months ago)
- Topics: bot, fastify, fastify-plugin, line, line-bot, sdk
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/fastify-line
- Size: 16.6 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# fastify-line
[](https://github.com/inyourtime/fastify-line/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/fastify-line)
[](https://biomejs.dev)
[](./LICENSE)
A Fastify plugin for seamless integration with the [LINE Messaging API](https://developers.line.biz/en/docs/messaging-api/overview/). It provides signature verification, raw body parsing, and exposes the official LINE Messaging API client on your Fastify instance.
---
## Features
- Signature verification for LINE webhooks
- Raw body parsing for webhook requests
- Exposes the official `@line/bot-sdk` Messaging API client as `fastify.line`
- Easy route integration with Fastify
## Installation
```bash
npm install fastify-line @line/bot-sdk
```
> **Note:** `@line/bot-sdk` is a peer dependency and must be installed separately.
## Compatibility
| Plugin Version | Fastify Version |
|:--------------:|:---------------:|
| `>=0.x` | `^5.x` |
## Usage
Register the plugin with your LINE channel credentials:
```ts
import Fastify from 'fastify'
import fastifyLine, { type WebhookRequestBody } from 'fastify-line'
const fastify = Fastify()
await fastify.register(fastifyLine, {
channelSecret: process.env.LINE_CHANNEL_SECRET!,
channelAccessToken: process.env.LINE_CHANNEL_ACCESS_TOKEN!,
})
fastify.post<{ Body: WebhookRequestBody }>(
'/webhook',
{
config: { lineWebhook: true }, // Enable LINE webhook handling for this route
},
async (request, reply) => {
const { events } = request.body
for (const event of events) {
if (event.type === 'message' && event.message.type === 'text') {
await fastify.line.client.replyMessage({
replyToken: event.replyToken,
messages: [
{
type: 'text',
text: `You said: ${event.message.text}`,
},
],
})
// or use blobClient
// fastify.line.blobClient
}
}
reply.send({ ok: true })
},
)
await fastify.listen({ port: 3000 })
```
### Skip Signature Verification
```ts
await fastify.register(fastifyLine, {
channelSecret: process.env.LINE_CHANNEL_SECRET!,
channelAccessToken: process.env.LINE_CHANNEL_ACCESS_TOKEN!,
skipVerify: true, // Skip signature verification
})
```
> **Warning:** Only use `skipVerify: true` in development/testing environments. Always verify signatures in production to ensure webhook security. If you skip automatic verification, you can manually verify signatures in your webhook handler using `validateSignature` from `@line/bot-sdk`.
## Options
| Option | Type | Required | Default | Description |
|----------------------|----------|----------|---------|------------------------------------------------------------------|
| `channelSecret` | string | Yes | - | Your LINE channel secret (for signature verification) |
| `channelAccessToken` | string | Yes | - | Your LINE channel access token (for Messaging API client) |
| `skipVerify` | boolean | No | `false` | Skip signature verification |
## How It Works
- Adds a `line` property to your Fastify instance: `fastify.line` (an instance of `MessagingApiClient` from `@line/bot-sdk`).
- For routes with `config: { lineWebhook: true }`:
- Parses the raw request body.
- Verifies the `X-Line-Signature` header using your channel secret.
- Throws `MissingSignatureError` or `InvalidSignatureError` if verification fails.
## Error Handling
The plugin throws custom errors for signature issues:
- `MissingSignatureError`: Thrown if the `X-Line-Signature` header is missing.
- `InvalidSignatureError`: Thrown if the signature is invalid.
You can handle these errors using Fastify's error handler:
```ts
fastify.setErrorHandler((err, _request, reply) => {
if (err instanceof MissingSignatureError) {
reply.status(401).send({
error: err.message,
message: 'The X-Line-Signature header is missing.',
})
}
if (err instanceof InvalidSignatureError) {
reply.status(401).send({
error: err.message,
message: 'The X-Line-Signature header is invalid.',
signature: err.signature,
})
}
// Default error handling
reply.send(err)
})
```
## Types
This plugin augments Fastify's types:
- `fastify.line`: The LINE Messaging API client
- `config.lineWebhook`: Set to `true` on a route to enable LINE webhook handling
## Contributing
Contributions are welcome!
## License
MIT