# 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.

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

### `request.org`

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

```typescript
request.org = {
    id: string,
}
```

{% hint style="warning" %}
`request.account`and `request.org` are both [getters and setters](https://fastify.dev/docs/latest/Reference/Decorators/#getters-and-setters) and will trigger errors if accessed outside of `instance.authorized()`or `instance.authenticated()`directives.
{% endhint %}

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

Discussed in [authorization](https://docs.novel.dev/novel-server/authorization "mention")

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

This uses the CASL `can`signature.

{% code title="app/api/v1/your-route/index.ts" lineNumbers="true" %}

```typescript
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');
    }
}
```

{% endcode %}

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](https://docs.novel.dev/novel-server/authorization "mention")

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

### `await request.verified()`

Check if the currently logged in user has a `verified`status.

{% code title="app/api/v1/your-route/index.ts" lineNumbers="true" %}

```typescript
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');
    }
}
```

{% endcode %}

### `await request.subscribed()`

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

{% code title="app/api/v1/your-route/index.ts" lineNumbers="true" %}

```typescript
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');
    }
}
```

{% endcode %}

### `request.ua()`

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

{% code title="app/api/v1/your-route/index.ts" lineNumbers="true" %}

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

{% endcode %}

Check the[ library definition for the ua object](https://github.com/mcollina/my-ua-parser#constructor).

## 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.

{% code title="app/api/v1/your-route/index.ts" lineNumbers="true" %}

```typescript
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');
    }
}
```

{% endcode %}

{% embed url="<https://docs.novel.dev/novel-server/routing/route-directives#cacheoptions>" %}

## Changelog

* 2024-12-20 - Initial Documentation