feat: extend contracts and roles for collection functions

packages/aeria-sdk/src/mirror.ts

@@ -14,7 +14,7 @@ const mirrorDts = (mirrorObj: any) => {
   SchemaWithId,
   MakeEndpoint,
   RequestMethod,
-  CollectionFunctions
+  CollectionFunctionsPaginated
 
 } from '@aeriajs/types'
 
@@ -58,7 +58,7 @@ declare module 'aeria-sdk' {
 
   type StrongelyTypedTLO = TopLevelObject & Endpoints & {
     [K in keyof MirrorDescriptions]: SchemaWithId<MirrorDescriptions[K]> extends infer Document
-      ? CollectionFunctions<Document> extends infer Functions
+      ? CollectionFunctionsPaginated<Document> extends infer Functions
         ? Omit<TLOFunctions, keyof Functions> & {
           [P in keyof Functions]: {
             POST: Functions[P]

packages/api/src/assets.ts

@@ -64,7 +64,7 @@ export const getFunction = async <
   acProfile?: ACProfile,
 ) => {
   if( acProfile ) {
-    if( !await isGranted(String(collectionName), String(functionName), acProfile) ) {
+    if( !await isGranted(collectionName, functionName, acProfile) ) {
       return left(ACErrors.AuthorizationError)
     }
   }

packages/api/src/collection/define.ts

@@ -1,4 +1,11 @@
-import type { SchemaWithId, Collection, Context, Description } from '@aeriajs/types'
+import type {
+  SchemaWithId,
+  Collection,
+  Context,
+  Contract,
+  Description,
+
+} from '@aeriajs/types'
 
 export const defineCollection = <
   TCollection extends Collection<TCollection extends Collection ? TCollection : never> extends infer Coll
@@ -9,13 +16,17 @@ export const defineCollection = <
     >
     : never,
   const TDescription extends Description<TDescription>,
+  const TFunctionContracts extends Partial<{
+    [P in keyof TFunctions]: Contract
+  }>,
   const TFunctions extends {
     [P: string]: (payload: any, context: Context<TDescription>, ...args: any[])=> any
   },
 >(
   collection: TCollection & {
     description: TDescription
     functions?: TFunctions
+    functionContracts?: TFunctionContracts
   },
 ) => {
   return collection as TCollection & {

packages/api/src/collection/index.ts

@@ -1,6 +1,7 @@
 export * from './cascadingRemove.js'
 export * from './define.js'
 export * from './description.js'
+export * from './pagination.js'
 export * from './preload.js'
 export * from './reference.js'
 export * from './traverseDocument.js'

packages/api/src/collection/pagination.ts

@@ -0,0 +1,26 @@
+import type { Context, Pagination, GetAllPayload } from '@aeriajs/types'
+
+export const makePagination = async (
+  payload: GetAllPayload<any>,
+  documents: any[],
+  context: Context
+): Promise<Pagination> => {
+  const limit = payload.limit
+    ? payload.limit
+    : context.config.paginationLimit!
+
+  const offset = payload.offset || 0
+
+  const recordsTotal = 'count' in context.collection.functions
+    ? await context.collection.functions.count(payload)
+    : await context.collection.model.countDocuments({
+      filters: payload.filters
+    })
+
+  return {
+    recordsCount: documents.length,
+    recordsTotal,
+    offset,
+    limit,
+  }
+}

packages/api/src/context.ts

@@ -28,6 +28,7 @@ const indepthCollection = (collectionName: string, collections: Record<string, C
         const childContext = await createContext({
           parentContext,
           collectionName,
+          inherited: true,
         })
 
         return collection.functions[functionName](props, childContext, ...args)
@@ -91,3 +92,4 @@ export const createContext = async (_options?: ContextOptions<any>) => {
   Object.assign(context, await internalCreateContext(options, context))
   return context
 }
+

packages/api/src/functions/getAll.ts

@@ -20,7 +20,7 @@ export const getAll = async <
 >(
   _payload: GetAllPayload<SchemaWithId<Context['description']>> | null,
   context: TContext,
-  options?: GetAllOptions,
+  options: GetAllOptions = {},
 ) => {
   const security = useSecurity(context)
   const payload = _payload || {}
@@ -103,7 +103,7 @@ export const getAll = async <
   }
 
   const result = await context.collection.model.aggregate(pipeline).toArray()
-  const documents: typeof result = []
+  const documents: TDocument[] = []
 
   for( const document of result ) {
     documents.push(unsafe(await traverseDocument(fill(document, context.description), context.description, {
@@ -114,5 +114,6 @@ export const getAll = async <
     })))
   }
 
-  return documents as TDocument[]
+  return documents
 }
+

packages/api/src/getEndpoints.ts

@@ -0,0 +1,51 @@
+import type { RoutesMeta, RouteUri } from '@aeriajs/http'
+import { getCollections, getRouter } from '@aeriajs/entrypoint'
+import { grantedFor } from '@aeriajs/access-control'
+import { deepMerge } from '@aeriajs/common'
+
+export const getEndpoints = async (): Promise<RoutesMeta> => {
+  const router = await getRouter()
+  const collections = await getCollections()
+
+  const functions: RoutesMeta = {}
+
+  for( const collectionName in collections ) {
+    const candidate = collections[collectionName]
+    const collection = typeof candidate === 'function'
+      ? candidate()
+      : candidate
+
+    const {
+      description,
+      functions: collectionFunctions,
+      functionContracts
+    } = collection
+
+    if( collectionFunctions ) {
+      for( const fnName in collectionFunctions ) {
+        const endpoint = `/${description.$id}/${fnName}`
+        const roles = await grantedFor(description.$id, fnName)
+
+        const contract = functionContracts && fnName in functionContracts
+          ? roles
+            ? Object.assign({ roles }, functionContracts[fnName])
+            : functionContracts[fnName]
+          : roles
+            ? { roles }
+            : null
+
+        functions[endpoint as RouteUri] = {
+          POST: contract
+        }
+      }
+    }
+  }
+
+  const result = deepMerge(
+    functions,
+    router.routesMeta
+  )
+
+  return result
+}
+

packages/api/src/index.ts

@@ -1,9 +1,10 @@
 export * from './assets.js'
 export * from './collection/index.js'
 export * from './context.js'
-export * from './token.js'
 export * from './database.js'
 export * from './functions/index.js'
+export * from './getEndpoints.js'
+export * from './token.js'
 export * from './use.js'
 export * as functions from './functions/index.js'
 export {

packages/builtins/src/functions/describe.ts

@@ -1,7 +1,7 @@
 import type { Context, Either } from '@aeriajs/types'
 import type { Description } from '@aeriajs/types'
-import { createContext, preloadDescription } from '@aeriajs/api'
-import { getCollections, getRouter } from '@aeriajs/entrypoint'
+import { createContext, preloadDescription, getEndpoints } from '@aeriajs/api'
+import { getCollections } from '@aeriajs/entrypoint'
 import { serialize, isLeft, left, unwrapEither } from '@aeriajs/common'
 import { getAvailableRoles } from '@aeriajs/access-control'
 import { authenticate } from '../collections/user/authenticate.js'
@@ -61,6 +61,7 @@ export const describe = async (contextOrPayload: Context | Payload) => {
       : candidate
 
     const { description: rawDescription } = collection
+
     const description = await preloadDescription(rawDescription)
     descriptions[description.$id] = description
   }
@@ -70,8 +71,7 @@ export const describe = async (contextOrPayload: Context | Payload) => {
   }
 
   if( props.router ) {
-    const router = await getRouter()
-    result.router = router.routesMeta
+    result.router = await getEndpoints()
   }
 
   if( props.noSerialize || !('response' in contextOrPayload) ) {

packages/http/@types/resources.d.ts

@@ -0,0 +1,5 @@
+import type { Collection } from '../src/types'
+
+declare global {
+  type Collections = Record<string, Collection>
+}

packages/http/src/contract.ts

@@ -1,15 +1,6 @@
-import type { Property } from '@aeriajs/types'
+import type { ContractWithRoles } from '@aeriajs/types'
 
-export type Contract =
-  | { response: Property | Property[] }
-  | { payload: Property }
-  | { query: Property }
-  | {
-    response?: Property | Property[]
-    payload?: Property
-    query?: Property
-  }
-
-export const defineContract = <const TContract extends Contract>(contract: TContract) => {
+export const defineContract = <const TContractWithRoles extends ContractWithRoles>(contract: TContractWithRoles) => {
   return contract
 }
+

packages/http/src/routing.ts

@@ -6,12 +6,12 @@ import type {
   InferProperty,
   InferResponse,
   PackReferences,
+  ContractWithRoles,
 } from '@aeriajs/types'
-import type { Contract } from './contract.js'
 
 import { REQUEST_METHODS } from '@aeriajs/types'
 import { Stream } from 'stream'
-import { pipe, left, isLeft, unwrapEither, deepMerge } from '@aeriajs/common'
+import { pipe, arraysIntersects, left, isLeft, unwrapEither, deepMerge } from '@aeriajs/common'
 import { validate } from '@aeriajs/validation'
 import { safeJson } from './payload.js'
 import { DEFAULT_BASE_URI } from './constants.js'
@@ -23,18 +23,23 @@ export type RouterOptions = {
   base?: RouteUri
 }
 
+export type RoutesMeta = Record<
+  RouteUri,
+  Partial<Record<RequestMethod, ContractWithRoles | null> | undefined>
+>
+
 export type Middleware = (context: Context)=> any
 
 export type RouteGroupOptions = {
   base?: RouteUri
 }
 
-type TypedContext<TContract extends Contract> = Omit<Context, 'request'> & {
+type TypedContext<TContractWithRoles extends ContractWithRoles> = Omit<Context, 'request'> & {
   request: Omit<Context['request'], 'payload' | 'query'> & {
-    payload: TContract extends { payload: infer Payload }
+    payload: TContractWithRoles extends { payload: infer Payload }
       ? PackReferences<InferProperty<Payload>>
       : never
-    query: TContract extends { query: infer Query }
+    query: TContractWithRoles extends { query: infer Query }
       ? InferProperty<Query>
       : any
   }
@@ -43,17 +48,32 @@ type TypedContext<TContract extends Contract> = Omit<Context, 'request'> & {
 export type ProxiedRouter<TRouter> = TRouter & Record<
   RequestMethod,
   <
-    TCallback extends (context: TypedContext<TContract>)=> TContract extends { response: infer Response }
+    TCallback extends (context: TypedContext<TContractWithRoles>)=> TContractWithRoles extends { response: infer Response }
       ? InferResponse<Response>
       : any,
-    const TContract extends Contract,
+    const TContractWithRoles extends ContractWithRoles,
   >(
     exp: RouteUri,
     cb: TCallback,
-    contract?: TContract
+    contract?: TContractWithRoles
   )=> ReturnType<typeof registerRoute>
 >
 
+const checkUnprocessable = (validationEither: ReturnType<typeof validate>, context: Context) => {
+  if( isLeft(validationEither) ) {
+    context.response.writeHead(422, {
+      'content-type': 'application/json',
+    })
+    return validationEither
+  }
+}
+
+const unsufficientRoles = (context: Context) => {
+  context.response.writeHead(403, {
+    'content-type': 'application/json'
+  })
+}
+
 export const matches = <TRequest extends GenericRequest>(
   req: TRequest,
   method: RequestMethod | RequestMethod[] | null,
@@ -88,7 +108,7 @@ export const registerRoute = async <TCallback extends (context: Context)=> any>(
   method: RequestMethod | RequestMethod[],
   exp: RouteUri,
   cb: TCallback,
-  contract?: Contract,
+  contract?: ContractWithRoles,
   options: RouterOptions = {},
 ) => {
   const match = matches(context.request, method, exp, options)
@@ -116,18 +136,21 @@ export const registerRoute = async <TCallback extends (context: Context)=> any>(
     Object.assign(context.request, match)
 
     if( contract ) {
-      const checkUnprocessable = (validationEither: ReturnType<typeof validate>) => {
-        if( isLeft(validationEither) ) {
-          context.response.writeHead(422, {
-            'content-type': 'application/json',
-          })
-          return validationEither
+      if( contract.roles ) {
+        if( !context.token.authenticated ) {
+          if( !contract.roles.includes('guest') ) {
+            return unsufficientRoles(context)
+          }
+        } else if( context.token.roles ) {
+          if( !arraysIntersects(context.token.roles, contract.roles) ) {
+            return unsufficientRoles(context)
+          }
         }
       }
 
       if( 'payload' in contract && contract.payload ) {
         const validationEither = validate(context.request.payload, contract.payload)
-        const error = checkUnprocessable(validationEither)
+        const error = checkUnprocessable(validationEither, context)
         if( error ) {
           return error
         }
@@ -138,7 +161,7 @@ export const registerRoute = async <TCallback extends (context: Context)=> any>(
           coerce: true,
         })
 
-        const error = checkUnprocessable(validationEither)
+        const error = checkUnprocessable(validationEither, context)
         if( error ) {
           return error
         }
@@ -206,18 +229,18 @@ export const createRouter = (options: Partial<RouterOptions> = {}) => {
   options.base ??= DEFAULT_BASE_URI
 
   const routes: ((_: unknown, context: Context, groupOptions?: RouteGroupOptions)=> ReturnType<typeof registerRoute>)[] = []
-  const routesMeta = {} as Record<RouteUri, Partial<Record<RequestMethod, Contract | null> | undefined>>
+  const routesMeta = {} as RoutesMeta
 
   const route = <
-    TCallback extends (context: TypedContext<TContract>)=> TContract extends { response: infer Response }
+    TCallback extends (context: TypedContext<TContractWithRoles>)=> TContractWithRoles extends { response: infer Response }
       ? InferResponse<Response>
-      : TContract,
-    const TContract extends Contract,
+      : TContractWithRoles,
+    const TContractWithRoles extends ContractWithRoles,
   >(
     method: RequestMethod | RequestMethod[],
     exp: RouteUri,
     cb: TCallback,
-    contract?: TContract,
+    contract?: TContractWithRoles,
   ) => {
     routesMeta[exp] ??= {}
     routesMeta[exp]![Array.isArray(method)