nestjs-appwrite
Version:
Easier Appwrite integration for your NestJS application.
195 lines (165 loc) • 6.51 kB
Markdown
# nestjs-appwrite
Easier Appwrite integration for your NestJS application.
## Overview
This is a core library developed by Coffee IT which offers easier integration with Appwrite when using the NestJS framework.
The library offers a few functionalities:
1. Appwrite database setup through decorators
2. A SecretStore service which can be configured to use AWS Parameter Store or env variables
3. AccessTokenGuard. This is a simple guard that verified the JWT token based on the JWT secret and adds an Appwrite Client in the body of the request
5. CustomLogger. This logger does a setup of the log levels and exposes a function to log objects
6. Generic utility functions
## Appwrite setup through decorators
The library will create your database collections and configures the attribute and indexes based on your schema decorators.
### Step 1: Configure the Appwrite Module
Setup the AppwriteModule inside your main AppModule and pass the required options.
Based on the useEnvVarsForSecrets boolean the library will either use env variables for secrets or otherwise AWS parameter store.
The library expects the following secrets:
```
JWT_SECRET=Secret that can be used to verify JWT tokens, only required when using AccessTokenGuard
APPWRITE_API_KEY=The Appwrite Api key
```
The names of the secrets need to be uppercase when using env variables and lowercase when using parameter store.
```typescript
({
imports: [
AppwriteModule.forRoot({
endpoint: Config.APPWRITE_ENDPOINT,
projectId: Config.APPWRITE_PROJECT_ID,
databaseId: Config.APPWRITE_DATABASE_ID,
awsRegion: AWS_REGION,
useEnvVarsForSecrets: Config.USE_ENV_VARS,
}),
],
})
export class AppModule {}
```
### Step 2: Create your schema
You can create Appwrite database schemas based on decorators. For example:
```typescript
import { ADMIN_TEAM_ID, EXPERIENCES_COLLECTION_ID, EXPERIENCES_COLLECTION_NAME } from '../../constants';
import { ExperienceType } from '../domain/experience-type.enum';
import { Permission, Role } from 'node-appwrite';
import { EnumProp, Index, Schema, StringProp } from 'appwrite-core';
import { Document } from 'appwrite-core';
import { ApiProperty, IntersectionType } from '@nestjs/swagger';
({
collectionId: EXPERIENCES_COLLECTION_ID,
collectionName: EXPERIENCES_COLLECTION_NAME,
permissions: [
Permission.read(Role.any()),
Permission.write(Role.team(ADMIN_TEAM_ID))
],
})
export class Experience {
()
()
title: string;
()
({ size: 30 })
({ type: 'unique', orders: 'DESC' })
coverImageId: string;
()
({ size: 1000 })
content: string;
({ enum: ExperienceType })
({ enum: ExperienceType })
type: ExperienceType;
}
export class ExperienceModel extends IntersectionType(Experience, Document) {}
```
### Step 3: Import your schema
Within the module that needs the schema you will have to import the schema. For example:
``` typescript
({
imports: [
AppwriteModule.forFeatureAsync([
{ class: Experience },
]),
],
providers: [],
controllers: [ExperienceController]
})
export class ExperienceModule {}
```
### Step 4: Use your schema in controllers/services
You're now ready to use the schema within your controllers and services.
The schema will be wrapped inside a AppwriteRepository class which offers many useful database operations.
Example usage within a controller:
```typescript
()
export class ExperienceController {
constructor(
(Experience.name) private readonly experienceRepo: AppwriteRepository<Experience>,
) {}
('experiences')
(AccessTokenGuard)
({ type: ExperienceModel })
public async createExperience(() client: ClientWithToken, () dto: CreateExperienceDto): Promise<ExperienceModel> {
return this.experienceRepo.asAppClient(client).createDocument(dto);
}
}
```
The ClientWithToken object is available here because it gets added to the request by the AccessTokenGuard.
You then have to use asAppClient() to make use of the permissions of the client.
That's it. When you start your service the database will be configured and you can create a document with the properties of the schema.
## Globally available services
This library exposes a few services that are globally available.
### Guards
You can simply import the AccessTokenGuard and use it in your controller
```typescript
(AccessTokenGuard)
```
### Appwrite server client provider
You can inject an instance of the appwrite server client like so:
```typescript
()
export class AppController implements OnApplicationBootstrap {
constructor(
(CLIENT_PROVIDER_NAME) private readonly rootClient: Client,
) {
}
public async onApplicationBootstrap(): Promise<void> {
await this.setupTeams();
}
private async setupTeams(): Promise<void> {
const teams = new Teams(this.rootClient);
try {
await teams.get(ADMIN_TEAM_ID);
} catch (err: any) {
if (err.code === HttpStatus.NOT_FOUND) {
await teams.create(ADMIN_TEAM_ID, ADMIN_TEAM_NAME);
this.logger.debug(`Created team with id ${ADMIN_TEAM_ID} and name ${ADMIN_TEAM_NAME}`);
return;
}
this.logger.error(err);
}
}
}
```
As you can see you can use the client to do any setup work yourself.
### Store service provider
Let's say you want to make use of a secret that might be configured inside parameter store on a server or as a env variable locally. \
You can then make use of SecretStoreService. Simply import the SecretStoreService inside your class like so:
```typescript
()
export class FirebaseService implements OnApplicationBootstrap {
private readonly logger = new Logger();
constructor(
private readonly storeService: SecretStoreService
) { }
public async onApplicationBootstrap(): Promise<void> {
await this.init();
}
private async init() {
let firebaseServiceAccount = await this.storeService.getSecretString(FIREBASE_SERVICE_ACCOUNT_SECRET);
if (!firebaseServiceAccount) {
this.logger.error(`Secret ${FIREBASE_SERVICE_ACCOUNT_SECRET} is undefined, unable to use Firebase`);
return;
}
admin.initializeApp({
credential: admin.credential.cert(firebaseServiceAccount)
});
}
}
```
In this example we get the Firebase service account secret from the SecretStoreService to setup firebase.