Request Helpers

This is a catalog of available convenience methods available in Novel registered using Fastify's request and reply decorators.

Request

request.account

This includes details on which user is accessing that request.

request.account = {
    id: string,
    role: string,
    verified: boolean,
};

request.org

This includes details on which organization is being used by the current request

request.org = {
    id: string,
}

request.accountand request.org are both getters and setters and will trigger errors if accessed outside of instance.authorized()or instance.authenticated()directives.

await request.can(action: string, subject: any, fields: string[])

Discussed in Authorization

A convenience method that allows you to check if the currently logged in user is allowed to take actiontowards the specific subject.

This uses the CASL cansignature.

app/api/v1/your-route/index.ts

export default function Route(instance) {
    instance.authenticated();
    instance.get('/your/route', handler);
    
    async function handler (request) {
        await request.can('read', 'projects');
        reply.send('ONLY FOR SESSIONS WITH projects:read PERMISSION');
    }
}

See https://github.com/madewithnovel/novel/blob/main/packages/novel/lib/session.js#L196

await request.cannot(action: string, subject: any, fields: string[])

Discussed in Authorization

This is the inverse of await request.can() above.

await request.verified()

Check if the currently logged in user has a verifiedstatus.

app/api/v1/your-route/index.ts

export default function Route(instance) {
    instance.authorized();
    instance.get('/your/route', handler);
    
    async function handler (request) {
        await request.verified();
        reply.send('ONLY FOR AUTHENTICATED API KEYS');
    }
}

await request.subscribed()

Check if the currently logged in organization has an active subscription.

app/api/v1/your-route/index.ts

export default function Route(instance) {
    instance.authorized();
    instance.get('/your/route', handler);
    
    async function handler (request) {
        await request.subscribed();
        reply.send('ONLY FOR SUBSCRIBED ORGANIZATIONS');
    }
}

request.ua()

A convenience method that exposes an object that has the user-agent parsed by the my-ua-parserlibrary.

app/api/v1/your-route/index.ts

export default function Route(instance) {
    instance.get('/your/route', handler);
    
    async function handler (request) {
        return request.ua();
    }
}

Check the library definition for the ua object.

Reply

reply.error(error: FastifyError)

A response builder that consolidates errors and produces an error format unique to Novel.

See https://github.com/madewithnovel/novel/blob/main/packages/novel/lib/server.js#L158

await reply.uncache(key: string, options?: CacheOptions)

This is a decorator to reply that you can use to manually purge a cached response.

app/api/v1/your-route/index.ts

export default function Route(instance) {
    instance.get('/your/route', handler);
    
    async function handler (request, reply) {
        await request.cache('custom-key');
        // do some specific logic
        reply.send('OK');
        await reply.uncache('custom-key');
    }
}

Route Directives | Novel

Changelog

• 2024-12-20 - Initial Documentation