@recursyve/nestjs-pidgey 11.0.0 → 11.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @recursyve/nestjs-pidgey
+
+## 11.1.0
+
+### Minor Changes
+
+- [`464b2b0`](https://github.com/Recursyve/nestjs-pidgey/commit/464b2b0c74d8424ef3a9bfef5257774f0ca612d9) Thanks [@gabrielroberge](https://github.com/gabrielroberge)! - Add a typed NestJS client for the Pidgey v2 API, with modules for API keys, attachments, OAuth clients, infrastructure, logs, mail, SMS, tenants, and webhooks. Module options can also be read from environment variables.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Recursyve
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,221 @@
+# @recursyve/nestjs-pidgey
+
+Typed NestJS client for the [Pidgey](https://github.com/recursyve/nestjs-pidgey) v2 API. It registers a configured HTTP client and exposes handwritten modules for API keys, attachments, OAuth clients, infrastructure, logs, mail, SMS, tenants, and webhooks.
+
+Only symbols exported from the package root (`@recursyve/nestjs-pidgey`) are part of the supported public API.
+
+## Install
+
+```sh
+npm install @recursyve/nestjs-pidgey
+```
+
+Peer dependencies: `@nestjs/common`, `@nestjs/core`, `reflect-metadata`, and `rxjs` (Nest 11+).
+
+## Setup
+
+Register `PidgeyModule` once in the application module. It is global by default, so feature modules can inject the Pidgey HTTP client without importing `PidgeyModule` again. Import the feature modules whose services you need.
+
+```ts
+import { Module } from "@nestjs/common";
+import {
+    ApiKeysModule,
+    AttachmentsModule,
+    ClientsModule,
+    InfrastructureModule,
+    LogsModule,
+    MailModule,
+    PidgeyModule,
+    SmsModule,
+    TenantsModule,
+    WebhooksModule
+} from "@recursyve/nestjs-pidgey";
+
+@Module({
+    imports: [
+        PidgeyModule.forRoot({
+            apiKey: "pidgey-api-key",
+            baseUrl: "https://pidgey.example/api",
+            tenantId: "tenant-id",
+            webhookSecret: "webhook-secret"
+        }),
+        ApiKeysModule,
+        AttachmentsModule,
+        ClientsModule,
+        InfrastructureModule,
+        LogsModule,
+        MailModule,
+        SmsModule,
+        TenantsModule,
+        WebhooksModule
+    ]
+})
+export class AppModule {}
+```
+
+`apiKey` and `tenantId` are required non-empty strings. `baseUrl` defaults to `https://pidgey.recursyve.dev/api`; when set, it must be an absolute HTTP or HTTPS URL, and trailing slashes are stripped. `webhookSecret` is optional unless you use `WebhookGuard`. Empty strings are rejected at registration.
+
+Any option you leave out is read from its environment variable:
+
+| Option          | Environment variable    | Default                            |
+| --------------- | ----------------------- | ---------------------------------- |
+| `apiKey`        | `PIDGEY_API_KEY`        | required                           |
+| `baseUrl`       | `PIDGEY_BASE_URL`       | `https://pidgey.recursyve.dev/api` |
+| `tenantId`      | `PIDGEY_TENANT_ID`      | required                           |
+| `webhookSecret` | `PIDGEY_WEBHOOK_SECRET` | none                               |
+
+Options passed to the module take precedence. To configure everything from the environment, call `PidgeyModule.forRoot()` with no arguments. If a required value is set neither in the options nor in the environment (an empty variable counts as missing), the application fails at startup with an error naming the missing variable.
+
+Every request sends that `apiKey` and `tenantId`. Mail, SMS, logs, attachments, API keys, OAuth clients, webhooks, and `TenantProvidersService` operate on that tenant. `TenantsService` creates, lists, and updates tenants, and reads a tenant by id. `InfrastructureService` exposes server information and health checks.
+
+Async registration:
+
+```ts
+PidgeyModule.forRootAsync({
+    imports: [ConfigModule],
+    inject: [ConfigService],
+    useFactory: (config: ConfigService) => ({
+        apiKey: config.getOrThrow("PIDGEY_API_KEY"),
+        baseUrl: config.get("PIDGEY_BASE_URL"),
+        tenantId: config.getOrThrow("PIDGEY_TENANT_ID"),
+        webhookSecret: config.get("PIDGEY_WEBHOOK_SECRET")
+    })
+});
+```
+
+Pass `isGlobal: false` if you do not want `PidgeyModule` to be global. On `forRoot`, put it next to the other options. On `forRootAsync`, put it next to `useFactory`, not inside the factory return value. When the module is not global, import `PidgeyModule` in the same module as the feature modules you use.
+
+Paged list methods return `Paged<T>` (`values`, plus optional `page`, `next`, and `total`). Entity types such as `Mail`, `ApiKey`, and `Tenant` are exported from the package root.
+
+## Errors
+
+All service methods throw when the HTTP request fails. They do not return error result objects.
+
+On a non-success response, the thrown value is the JSON body when the response parses as JSON, or the response text otherwise. Network and other transport failures throw as usual.
+
+## Infrastructure
+
+Inject `InfrastructureService` after importing `InfrastructureModule`. `getServerInfo()` returns a `ServerInfo` (`mode` and `version`). `getHealth()` returns a `HealthCheck`.
+
+```ts
+const info = await this.infrastructure.getServerInfo();
+const health = await this.infrastructure.getHealth();
+```
+
+## API keys
+
+Inject `ApiKeysService` after importing `ApiKeysModule`. Create, list, and update keys. `create()` returns a `CreatedApiKey` that includes the secret once; `findAll()` returns `Paged<ApiKey>` without it.
+
+## Attachments
+
+Inject `AttachmentsService` after importing `AttachmentsModule`. Upload `File` or `Blob` values, then pass the returned id as `attachmentRefId` when sending mail.
+
+```ts
+const attachment = await this.attachments.upload({
+    attachments: [new File(["invoice"], "invoice.pdf", { type: "application/pdf" })]
+});
+
+await this.mails.send({
+    to: ["billing@example.com"],
+    subject: "Invoice",
+    text: "See attached.",
+    attachmentRefId: attachment._id
+});
+```
+
+## OAuth clients
+
+Inject `OauthClientsService` after importing `ClientsModule`. `create()` creates a client on the current tenant, `add()` attaches an existing client id, `findAll()` lists clients, and `update()` changes name and scopes.
+
+## Logs
+
+Inject `LogsService` after importing `LogsModule`. `find()` lists mail or SMS logs for a time range.
+
+```ts
+const logs = await this.logs.find({
+    from: "2026-01-01T00:00:00Z",
+    to: "2026-01-31T23:59:59Z",
+    type: "mail"
+});
+```
+
+## Mail
+
+Inject `MailsService` or `MailTemplatesService` after importing `MailModule`.
+
+```ts
+import { Injectable } from "@nestjs/common";
+import { MailsService } from "@recursyve/nestjs-pidgey";
+
+@Injectable()
+export class NotificationsService {
+    constructor(private readonly mails: MailsService) {}
+
+    public async sendWelcome(email: string): Promise<void> {
+        await this.mails.send({
+            to: [email],
+            subject: "Welcome",
+            templateId: "welcome",
+            variables: { name: "Ada" }
+        });
+    }
+}
+```
+
+`MailsService.find()` lists sent mail. `MailTemplatesService` can create, list, fetch by id or name, update, and `remove()` templates, and list provider templates with `findProviderTemplates()`.
+
+## SMS
+
+Inject `SmsService` or `SmsTemplatesService` after importing `SmsModule`.
+
+```ts
+await this.sms.send({
+    to: ["+15145550100"],
+    templateId: "otp",
+    variables: { code: "123456" }
+});
+```
+
+`SmsService.find()` lists sent SMS. `SmsTemplatesService` can create, list, fetch by id or name, update, and `remove()` templates.
+
+## Tenants
+
+Inject `TenantsService` or `TenantProvidersService` after importing `TenantsModule`.
+
+`TenantsService` creates, lists, fetches, and updates tenants, and lists a tenant's modules with `findModules(id)`. `TenantProvidersService` enables mail or SMS on the current tenant, configures the provider, or patches the default sender.
+
+```ts
+await this.tenantProviders.enableMail();
+await this.tenantProviders.configureMail({
+    type: "mailgun",
+    defaultSender: "noreply@example.com",
+    mailgun: {
+        domain: "mg.example.com",
+        apiKey: "mailgun-api-key"
+    }
+});
+```
+
+## Webhooks
+
+Import `WebhooksModule` and set `webhookSecret` on `PidgeyModule`. `WebhooksService` can `create()` listeners, `findAll()`, `findSecret()`, and `remove()` a listener.
+
+`WebhookGuard` verifies `Pidgey-Webhook-Signature` (hex HMAC-SHA256 of `eventType:timestamp`). Invalid signatures throw `NotAcceptableException`.
+
+```ts
+import { Body, Controller, Post, UseGuards } from "@nestjs/common";
+import { MailStatusUpdatedWebhookEvent, WebhookGuard } from "@recursyve/nestjs-pidgey";
+
+@Controller("webhooks/pidgey")
+export class WebhooksController {
+    @Post("mail")
+    @UseGuards(WebhookGuard)
+    public onMailStatus(@Body() event: MailStatusUpdatedWebhookEvent): void {
+        // event.data is a Mail
+    }
+}
+```
+
+## License
+
+MIT