@gokiteam/goki-dev 0.2.0

package/patterns/api/[collectionName]/Permissions.md

@@ -0,0 +1,81 @@
+# API Permissions Pattern
+
+For API gateway microservices, define permission combinations for each endpoint.
+
+## Permission combination structure
+
+Coding pattern:
+```javascript
+export const Permissions = {
+  create: [
+    ['property:write', 'device:write']
+  ],
+  update: [
+    ['property:write', 'device:write']
+  ],
+  details: [
+    ['property:read', 'device:read']
+  ],
+  list: [
+    ['property:read', 'device:read']
+  ],
+  delete: [
+    ['property:write', 'device:write', 'device:delete']
+  ]
+}
+```
+
+## Router integration
+
+Permissions are used in the middleware stack:
+
+```javascript
+import KoaRouter from 'koa-router'
+import { PermissionsEvaluator, JoiValidator } from '@gokiteam/koa'
+
+import { Schemas } from './Schemas.js'
+import { Controllers } from './Controllers.js'
+import { Permissions } from './Permissions.js'
+
+const Router = new KoaRouter()
+const v1 = new KoaRouter({ prefix: '/v1/devices' })
+
+v1.post(
+  '/create',
+  PermissionsEvaluator({ combinations: Permissions.create }),
+  JoiValidator({ schema: Schemas.create }),
+  Controllers.create
+)
+
+Router.use(v1.routes())
+export { Router }
+```
+
+## Permission combinations
+
+Each endpoint can have multiple permission combinations (OR logic):
+
+```javascript
+export const Permissions = {
+  create: [
+    ['admin'],  // Admin can create
+    ['property:write', 'device:write']  // Or users with both permissions
+  ],
+  delete: [
+    ['admin'],  // Only admin can delete
+    ['property:owner', 'device:delete']  // Or property owners with delete permission
+  ]
+}
+```
+
+## Non-gateway microservices
+
+For non-gateway microservices (internal services), no Permissions.js file is needed. The Router middleware stack is:
+
+```javascript
+v1.post(
+  '/create',
+  JoiValidator({ schema: Schemas.create }),
+  Controllers.create
+)
+```

package/patterns/api/[collectionName]/Router.md

@@ -0,0 +1,83 @@
+# API Route definition
+Each api endpoint:
+- The routing rules should be defined in "src/api/[collection]/Router.js" file.
+- The router is a koa router with a stack of middleware registered on each endpoint route.
+- The router should be added to "src/HttpServer.js" router list.
+
+The common scenario is to have a v1 router like:
+```javascript
+import KoaRouter from 'koa-router'
+
+const Router = new KoaRouter()
+const v1 = new KoaRouter({ prefix: '/v1/[collection]' })
+
+// route defintions...
+
+Router.use(v1.routes())
+
+export { Router }
+```
+
+In some cases we might have other versions like:
+```javascript
+import KoaRouter from 'koa-router'
+
+const Router = new KoaRouter()
+const v1 = new KoaRouter({ prefix: '/v1/[collection]' })
+const v2 = new KoaRouter({ prefix: '/v2/[collection]' })
+
+// v1 route defintions...
+
+// v2 route defintions
+
+Router.use(v1.routes())
+Router.use(v2.routes())
+
+export { Router }
+```
+
+For each endpoint the common middleware stack is "path", "validation", "controller" like:
+```javascript
+import KoaRouter from 'koa-router'
+
+import { Schemas } from './Schemas.js'
+import { Controllers } from './Controllers.js'
+
+const Router = new KoaRouter()
+const v1 = new KoaRouter({ prefix: '/v1/[collection]' })
+
+v1
+  .post(
+    '/create',
+    JoiValidator({ schema: Schemas.create }),
+    Controllers.create
+  )
+
+Router.use(v1.routes())
+
+export { Router }
+```
+
+For API gateway microservices, the common middleware stack is "path", "permission checks", "validation", "controller" like:
+```javascript
+import KoaRouter from 'koa-router'
+
+import { Schemas } from './Schemas.js'
+import { Controllers } from './Controllers.js'
+import { Permissions } from './Permissions.js'
+
+const Router = new KoaRouter()
+const v1 = new KoaRouter({ prefix: '/v1/[collection]' })
+
+v1
+  .post(
+    '/create',
+    PermissionsEvaluator({ combinations: Permissions.create }),
+    JoiValidator({ schema: Schemas.create }),
+    Controllers.create
+  )
+
+Router.use(v1.routes())
+
+export { Router }
+```

package/patterns/api/[collectionName]/Schemas.md

@@ -0,0 +1,197 @@
+# API Schema definition and rules
+Each API endpoint should have schemas for:
+- success response
+- error responses
+  - For each error reason being thrown from the related logic, specify Oops error meta object
+
+For entities and shared objects, we define schemas inside "src/schemas" directory in the root of the project then use
+them inside "src/api/[collection]/Schemas.js"
+
+Coding pattern:
+
+Consider the endpoint is `/v1/apps/activateConnection`.
+
+The content of "src/schemas/App.js"
+```javascript
+import { Joi } from '@gokiteam/koa'
+
+import { CategoryValues } from '../enums/Category.js'
+import { PermissionValues } from '../enums/Permission.js'
+import { AppStatusValues } from '../enums/AppStatus.js'
+
+export const App = Joi.object().keys({
+  id: Joi.string().uuid(),
+  name: Joi.string(),
+  category: Joi.string().valid(...CategoryValues),
+  logo: Joi.object().keys({
+    url: Joi.string().uri(),
+    publicId: Joi.string()
+  }).allow(null),
+  summary: Joi.string(),
+  description: Joi.string(),
+  supportEmail: Joi.string().email(),
+  isPrivate: Joi.boolean(),
+  isCustom: Joi.boolean(),
+  status: Joi.string().valid(...AppStatusValues),
+  partnerId: Joi.string().uuid().allow(null),
+  externalLinks: Joi.array().items(Joi.object().keys({
+    title: Joi.string(),
+    url: Joi.string().uri()
+  })),
+  permissions: Joi.array().items(Joi.string().valid(...PermissionValues)),
+  createdAt: Joi.string(),
+  updatedAt: Joi.string()
+})
+```
+
+The content of "src/api/apps/Schemas.js"
+```javascript
+import { Joi } from '@gokiteam/koa'
+
+import { ErrorReason } from '../../enums/ErrorReason.js'
+import { App } from '../../schemas/App.js'
+
+export const Schemas = {
+  // other endpoints schema definitions ...
+  activateConnection: {
+    request: {
+      body: {
+        id: Joi.string().uuid().required(),
+        partnerId: Joi.string().uuid().required(), 
+        propertyId: Joi.string().uuid().required()
+      }
+    },
+    responses: {
+      success: { app: App },
+      [ErrorReason.invalidAppId]: {
+        traceId: Joi.string().required(),
+        id: Joi.string().uuid().required()
+      },
+      [ErrorReason.connectionDoesNotExist]: {
+        traceId: Joi.string().required(),
+        id: Joi.string().uuid().required(),
+        propertyId: Joi.string().uuid().required()
+      },
+      [ErrorReason.connectionIsAlreadyActive]: {
+        traceId: Joi.string().required(),
+        id: Joi.string().uuid().required(),
+        propertyId: Joi.string().uuid().required()
+      },
+      [ErrorReason.insufficientPermission]: {
+        traceId: Joi.string().required(),
+        id: Joi.string().uuid().required(),
+        propertyId: Joi.string().uuid().required()
+      }
+    }
+  }
+}
+```
+
+The summarized content of "src/api/apps/Logic.js"
+```javascript
+export const Logic = {
+  // other endpoint logic implementation ...
+  async activateConnection (params) {
+    // some code
+    if (!hasAccess) {
+      throw Oops.permissionDenied('You are not allowed to activate the connection')
+        .reason(ErrorReason.insufficientPermission).resource(logicName).meta({ traceId, partnerId, id })
+    }
+    // some code
+    if (!appExists || app.doc.partnerId !== partnerId) {
+      throw Oops.notFound('The given app ID does not exist!')
+        .reason(ErrorReason.invalidAppId).resource(logicName).meta({ traceId, id })
+    }
+    // some code
+    if (!exists) {
+      throw Oops.notAcceptable('There is no connection to activate!')
+        .reason(ErrorReason.connectionDoesNotExist).resource(logicName).meta({ traceId, id, propertyId })
+    }
+    if (connection.doc.status === ConnectionStatus.active) {
+      throw Oops.notAcceptable('The connection is already active!')
+        .reason(ErrorReason.connectionIsAlreadyActive).resource(logicName).meta({ traceId, id, propertyId })
+    }
+    // some code
+    return { app: app.mask() }
+  }
+}
+```
+
+If an API endpoint returns 204 status, the schema should be like:
+```javascript
+export const Schemas = {
+  // other endpoints schemas ...
+  emptyResponseEndpoint: {
+    request: { /* defintion */ },
+    responses: {
+      success: {},
+      // error reasons ...
+    }
+  }
+}
+```
+
+If an API endpoint input is a file, the schema should be like:
+```javascript
+import { Default } from '../../configs/Default.js'
+
+export const Schemas = {
+  // other endpoints schemas ...
+  createUsersWithCsv: {
+    request: {
+      csvFile: Joi.object().unknown().keys({
+        koaAddedFields: {
+          contentType: Joi.string().valid(Default.csvFile.correctMimType),
+          size: Joi.number()
+            .max(Default.csvFile.maxFileSizeMb)
+            .message(`The maximum supported file size is ${Default.csvFile.maxFileSizeMb}Mb`),
+          filename: Joi.string()
+        }
+      }).required()
+    },
+    responses: { /* definition */ }
+  }
+}
+```
+
+If an API endpoint is a list endpoint with pagination, filtering, and sorting:
+```javascript
+import { Joi } from '@gokiteam/koa'
+
+import { Device } from '../../schemas/Device.js'
+import { ErrorReason } from '../../enums/ErrorReason.js'
+
+export const Schemas = {
+  // other endpoints schema definitions ...
+  list: {
+    request: {
+      body: {
+        propertyId: Joi.string().uuid().required(),
+        query: Joi.string().optional(),
+        filter: Joi.object({
+          status: Joi.string().optional(),
+          model: Joi.number().optional()
+        }).optional(),
+        page: Joi.object({
+          limit: Joi.number().integer().min(1).max(100).default(20),
+          offset: Joi.number().integer().min(0).default(0)
+        }).optional(),
+        sort: Joi.array().items(Joi.object({
+          field: Joi.string().required(),
+          order: Joi.string().valid('asc', 'desc').required()
+        })).optional()
+      }
+    },
+    responses: {
+      success: {
+        devices: Joi.array().items(Device),
+        total: Joi.number().integer()
+      },
+      [ErrorReason.invalidPropertyId]: {
+        traceId: Joi.string().required(),
+        propertyId: Joi.string().uuid().required()
+      }
+    }
+  }
+}
+```

package/patterns/configs/Patterns.md

@@ -0,0 +1,7 @@
+# Config definition rules
+- All config should be added to the "src/configs" directory.
+- All values should be defined as environment variables.
+- The environment variables should be added to "config.development" and "config.test" files in the root of the project.
+- The default values or constants should be added to "Default.js"
+- All configs of application's dependent services and tools like databases, cache, search engine, cloud services, etc. should be added to "Application.js"
+- All other microservice API base URLs should be added to "BaseUrls.js"

package/patterns/enums/Patterns.md

@@ -0,0 +1,24 @@
+## Enums definition patterns
+
+We define enums when we see:
+- Finite, Known Sets of Values
+- Statuses or States
+- Categories or Types
+- Options
+
+All enums should be defined as objects inside "src/enums" directory in the root of the project.
+The file name should be same as the enum name.
+
+Coding pattern:
+
+The content of "src/enums/Gender.js":
+```javascript
+export const Gender = Object.freeze({
+  male: 'male',
+  female: 'female',
+  other: 'other'
+})
+
+export const GenderValues = Object.values(Gender)
+
+```

package/patterns/errorHandling/Patterns.md

@@ -0,0 +1,185 @@
+# Error Handling Patterns
+
+## When to use Oops vs throw
+
+### Use Oops for known business logic errors
+- Validation failures
+- Resource not found
+- Permission denied
+- Logical constraints violated
+
+### Use throw for unexpected errors
+- Unknown errors that should trigger retry
+- System failures
+- External service failures
+
+### Use ProtocolError for device protocol errors
+- Invalid protocol packets
+- Encryption failures
+- Device-specific errors
+
+## Error structure pattern
+
+All Oops errors should include:
+- **reason**: from ErrorReason enum
+- **resource**: function name (logicName)
+- **meta**: traceId + relevant context
+
+Coding pattern:
+```javascript
+import { Oops } from '@gokiteam/oops'
+import { ErrorReason } from '../enums/ErrorReason.js'
+
+export const Logic = {
+  async create (params) {
+    const { data, traceId } = params
+    const { email } = data
+    const logicName = Logic.create.name
+    const exists = await User.doesExistCompositeId({ email })
+    if (exists) {
+      throw Oops.notAcceptable('The email already exists')
+        .reason(ErrorReason.userAlreadyExists)
+        .resource(logicName)
+        .meta({ traceId, email })
+    }
+    // ... logic
+  }
+}
+```
+
+## Common Oops error types
+
+```javascript
+// Not found (404)
+throw Oops.notFound('Device not found')
+  .reason(ErrorReason.deviceNotFound)
+  .resource(logicName)
+  .meta({ traceId, macAddress })
+
+// Invalid argument (400)
+throw Oops.invalidArgument('Invalid MAC address format')
+  .reason(ErrorReason.invalidMacAddress)
+  .resource(logicName)
+  .meta({ traceId, macAddress })
+
+// Not acceptable (406)
+throw Oops.notAcceptable('Device already exists')
+  .reason(ErrorReason.deviceAlreadyExists)
+  .resource(logicName)
+  .meta({ traceId, macAddress })
+
+// Permission denied (403)
+throw Oops.permissionDenied('Insufficient permissions')
+  .reason(ErrorReason.insufficientPermission)
+  .resource(logicName)
+  .meta({ traceId, userId })
+```
+
+## Error chaining with .previous()
+
+When catching and re-throwing errors, use `.previous()` to maintain error chain:
+
+```javascript
+export const Logic = {
+  async create (params) {
+    const { data, traceId } = params
+    const { email } = data
+    const logicName = Logic.create.name
+    try {
+      const result = await externalService.createUser(email)
+      return { user: result }
+    } catch (error) {
+      throw Oops.internal('Failed to create user in external service')
+        .reason(ErrorReason.externalServiceFailed)
+        .resource(logicName)
+        .previous(error)  // Chain the original error
+        .meta({ traceId, email })
+    }
+  }
+}
+```
+
+## ErrorReason enum usage
+
+All error reasons should be defined in `src/enums/ErrorReason.js`:
+
+```javascript
+export const ErrorReason = Object.freeze({
+  deviceNotFound: 'deviceNotFound',
+  deviceAlreadyExists: 'deviceAlreadyExists',
+  invalidMacAddress: 'invalidMacAddress',
+  userAlreadyExists: 'userAlreadyExists',
+  insufficientPermission: 'insufficientPermission'
+  // ... more reasons
+})
+```
+
+## Logging patterns
+
+### Info logging
+```javascript
+import { Logger } from '../singletons/Logger.js'
+import { LogEvent } from '../enums/LogEvent.js'
+
+Logger.log({
+  level: 'info',
+  message: 'Processing event',
+  data: { event: LogEvent.processingEvent, deviceId, traceId }
+})
+```
+
+### Warning logging
+```javascript
+Logger.log({
+  level: 'warn',
+  message: 'Device not found',
+  data: { event: LogEvent.deviceNotFound, deviceId, traceId }
+})
+```
+
+### Error logging
+```javascript
+import { ConvertErrorToLog } from '@gokiteam/utils'
+
+Logger.log(ConvertErrorToLog({
+  error,
+  message: 'Failed to process event',
+  data: { event: LogEvent.eventProcessingFailed, traceId }
+}))
+```
+
+## Subscriber error handling
+
+### Known errors - don't retry
+```javascript
+async process ({ data, attributes }) {
+  const traceId = this.getTraceId({ attributes })
+  try {
+    // ... processing logic
+  } catch (error) {
+    if (error.isOops) {
+      const knownErrorReasons = [
+        ErrorReason.deviceNotFound,
+        ErrorReason.invalidMqttClient
+      ]
+      if (knownErrorReasons.includes(error.data.reason)) {
+        // Don't retry - mark as failed
+        return { state: SubscriberResultState.processFailed, error: error.data }
+      }
+    }
+    // Unknown error - let it throw to trigger retry
+    throw error
+  }
+}
+```
+
+### Unknown errors - trigger retry
+```javascript
+async process ({ data, attributes }) {
+  const traceId = this.getTraceId({ attributes })
+  // Don't catch unknown errors - let them throw
+  // Pub/Sub will retry automatically
+  const result = await someOperation({ traceId })
+  return { state: SubscriberResultState.processedSuccessfully }
+}
+```