@maestro-js/agent-skills 1.0.0-alpha.2 → 1.0.0-alpha.21

package/skills/maestro-examples/references/cadence/packages/services/src/index.ts

@@ -0,0 +1,23 @@
+import './maestro.ts'
+export { type DeviceContext } from './maestro.ts'
+export { AuthService } from './auth/index.ts'
+export { OrganizationService } from './organization/index.ts'
+export { UserService } from './user/index.ts'
+export { ContactService } from './contact/index.ts'
+export { InteractionService } from './interaction/index.ts'
+export { Db } from '@maestro-js/db'
+export { Cache } from '@maestro-js/cache'
+export { Hash } from '@maestro-js/hash'
+export { Crypt } from '@maestro-js/crypt'
+export { Auth } from '@maestro-js/auth'
+export { Password } from '@maestro-js/password'
+export { Helpers } from '@maestro-js/helpers'
+export { Session } from '@maestro-js/session'
+export { RateLimiting } from '@maestro-js/rate-limiting'
+export { Queue } from '@maestro-js/queue'
+export { RecurringJobs } from '@maestro-js/recurring-jobs'
+export { Mail } from '@maestro-js/mail'
+export { Log } from '@maestro-js/log'
+export { Permissions } from '@maestro-js/permissions'
+export { CustomErrors } from '@maestro-js/custom-errors'
+export { H } from './testing/index.ts'

package/skills/maestro-examples/references/cadence/packages/services/src/interaction/index.ts

@@ -0,0 +1,25 @@
+import {
+  LogInteraction,
+  EditInteraction,
+  DeleteInteraction,
+  ListRecent,
+  InteractionNotFoundError,
+  ContactNotFoundError,
+  ForbiddenError,
+  EmptyBodyError,
+  BodyTooLongError
+} from './interaction-use-cases.ts'
+
+export const InteractionService = {
+  LogInteraction,
+  EditInteraction,
+  DeleteInteraction,
+  ListRecent,
+  errors: {
+    InteractionNotFoundError,
+    ContactNotFoundError,
+    ForbiddenError,
+    EmptyBodyError,
+    BodyTooLongError
+  }
+}

package/skills/maestro-examples/references/cadence/packages/services/src/interaction/interaction-db-provider.test.ts

@@ -0,0 +1,128 @@
+import { test } from 'beartest-js'
+import { expect } from 'expect'
+import { instantFns } from 'iso-fns'
+import { H } from '../testing/index.ts'
+import { interactionDbProvider } from './interaction-db-provider.ts'
+
+const org = H.OrganizationSeed({ id: 1 })
+const user = H.UserSeed({ id: 1, organizationId: 1 })
+const contact = H.ContactSeed({ id: 1, organizationId: 1 })
+const pipe = H.SeedPipe(org, user, contact)
+
+test.beforeEach(async () => {
+  await pipe.setup()
+})
+test.afterEach(async () => {
+  await pipe.teardown()
+})
+
+const createdIds: number[] = []
+test.afterEach(async () => {
+  for (const id of createdIds) {
+    await interactionDbProvider.hardDelete(id)
+  }
+  createdIds.length = 0
+})
+
+test('create and getById', async () => {
+  const now = instantFns.now()
+  const id = await interactionDbProvider.create({
+    contactId: 1,
+    userId: 1,
+    type: 'note',
+    subject: 'Follow up',
+    body: 'Discussed project timeline',
+    date: now
+  })
+  createdIds.push(id)
+
+  const interaction = await interactionDbProvider.getById(id)
+  expect(interaction).not.toBeNull()
+  expect(interaction!.type).toBe('note')
+  expect(interaction!.subject).toBe('Follow up')
+  expect(interaction!.body).toBe('Discussed project timeline')
+  expect(interaction!.contactId).toBe(1)
+  expect(interaction!.userId).toBe(1)
+  expect(interaction!.deletedDate).toBeNull()
+})
+
+test('update', async () => {
+  const now = instantFns.now()
+  const id = await interactionDbProvider.create({
+    contactId: 1,
+    userId: 1,
+    type: 'note',
+    subject: 'Original',
+    body: 'Original body',
+    date: now
+  })
+  createdIds.push(id)
+
+  await interactionDbProvider.update(id, {
+    type: 'email',
+    subject: 'Updated',
+    body: 'Updated body',
+    date: now
+  })
+
+  const interaction = await interactionDbProvider.getById(id)
+  expect(interaction!.type).toBe('email')
+  expect(interaction!.subject).toBe('Updated')
+  expect(interaction!.body).toBe('Updated body')
+})
+
+test('listByContactId', async () => {
+  const now = instantFns.now()
+  const id = await interactionDbProvider.create({
+    contactId: 1,
+    userId: 1,
+    type: 'note',
+    subject: null,
+    body: 'Test note',
+    date: now
+  })
+  createdIds.push(id)
+
+  const list = await interactionDbProvider.listByContactId(1)
+  expect(list.length).toBeGreaterThanOrEqual(1)
+  expect(list.some((i) => i.id === id)).toBe(true)
+})
+
+test('listRecent', async () => {
+  const now = instantFns.now()
+  const id = await interactionDbProvider.create({
+    contactId: 1,
+    userId: 1,
+    type: 'email',
+    subject: 'Quarterly review',
+    body: 'Went well',
+    date: now
+  })
+  createdIds.push(id)
+
+  const recent = await interactionDbProvider.listRecent(1)
+  expect(recent.length).toBeGreaterThanOrEqual(1)
+
+  const match = recent.find((i) => i.id === id)
+  expect(match).not.toBeUndefined()
+  expect(match!.contactName).toBeDefined()
+  expect(match!.userName).toBeDefined()
+})
+
+test('softDelete', async () => {
+  const now = instantFns.now()
+  const id = await interactionDbProvider.create({
+    contactId: 1,
+    userId: 1,
+    type: 'note',
+    subject: null,
+    body: 'To be deleted',
+    date: now
+  })
+  createdIds.push(id)
+
+  await interactionDbProvider.softDelete(id)
+
+  const interaction = await interactionDbProvider.getById(id)
+  expect(interaction).toBeNull()
+})

package/skills/maestro-examples/references/cadence/packages/services/src/interaction/interaction-db-provider.ts

@@ -0,0 +1,98 @@
+import { Db } from '@maestro-js/db'
+import { InteractionSchemas } from '@cadence/schemas'
+import { instantFns } from 'iso-fns'
+
+type Interaction = InteractionSchemas.interactionModel
+
+async function create(
+  data: Pick<Interaction, 'contactId' | 'userId' | 'type' | 'subject' | 'body' | 'date'>
+): Promise<number> {
+  const now = instantFns.formatISO9075(instantFns.now())
+  const result = await Db.insert(
+    'INSERT INTO interactions (contactId, userId, type, subject, body, date, createdDate, lastModifiedDate) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+    [data.contactId, data.userId, data.type, data.subject ?? null, data.body, instantFns.formatISO9075(data.date), now, now]
+  )
+  return result.insertId
+}
+
+async function getById(id: number): Promise<Interaction | null> {
+  const rows = await Db.select('SELECT * FROM interactions WHERE id = ? AND deletedDate IS NULL', [id])
+  const row = rows[0]
+  if (!row) return null
+  return InteractionSchemas.interactionModel.parse(row)
+}
+
+async function listByContactId(contactId: number): Promise<Interaction[]> {
+  const rows = await Db.select('SELECT * FROM interactions WHERE contactId = ? AND deletedDate IS NULL ORDER BY date DESC', [
+    contactId
+  ])
+  return rows.map((row) => InteractionSchemas.interactionModel.parse(row))
+}
+
+async function listRecent(orgId: number): Promise<(Interaction & { contactName: string; userName: string })[]> {
+  const rows = await Db.select(
+    `SELECT i.*, CONCAT(c.firstName, COALESCE(CONCAT(' ', c.lastName), '')) AS contactName, u.name AS userName
+     FROM interactions i
+     JOIN contacts c ON i.contactId = c.id
+     JOIN users u ON i.userId = u.id
+     WHERE c.organizationId = ? AND i.deletedDate IS NULL
+     ORDER BY i.date DESC`,
+    [orgId]
+  )
+  return rows.map((row) => ({
+    ...InteractionSchemas.interactionModel.parse(row),
+    contactName: row.contactName as string,
+    userName: row.userName as string
+  }))
+}
+
+async function update(id: number, data: Pick<Interaction, 'type' | 'subject' | 'body' | 'date'>): Promise<void> {
+  const now = instantFns.formatISO9075(instantFns.now())
+  await Db.update('UPDATE interactions SET type = ?, subject = ?, body = ?, date = ?, lastModifiedDate = ? WHERE id = ?', [
+    data.type,
+    data.subject ?? null,
+    data.body,
+    instantFns.formatISO9075(data.date),
+    now,
+    id
+  ])
+}
+
+async function softDelete(id: number): Promise<void> {
+  const now = instantFns.formatISO9075(instantFns.now())
+  await Db.update('UPDATE interactions SET deletedDate = ?, lastModifiedDate = ? WHERE id = ?', [now, now, id])
+}
+
+async function seedCreate(data: Interaction): Promise<void> {
+  const now = instantFns.formatISO9075(instantFns.now())
+  await Db.insert(
+    'INSERT INTO interactions (id, contactId, userId, type, subject, body, date, deletedDate, createdDate, lastModifiedDate) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
+    [
+      data.id,
+      data.contactId,
+      data.userId,
+      data.type,
+      data.subject ?? null,
+      data.body,
+      instantFns.formatISO9075(data.date),
+      data.deletedDate ?? null,
+      now,
+      now
+    ]
+  )
+}
+
+async function hardDelete(id: number): Promise<void> {
+  await Db.delete('DELETE FROM interactions WHERE id = ?', [id])
+}
+
+export const interactionDbProvider = {
+  create,
+  getById,
+  listByContactId,
+  listRecent,
+  update,
+  softDelete,
+  seedCreate,
+  hardDelete
+}

package/skills/maestro-examples/references/cadence/packages/services/src/interaction/interaction-use-cases.ts

@@ -0,0 +1,171 @@
+import z from 'zod'
+import sanitize from 'sanitize-html'
+import { Log } from '@maestro-js/log'
+import { Permissions } from '@maestro-js/permissions'
+import { CustomErrors } from '@maestro-js/custom-errors'
+import { InteractionSchemas, UserSchemas } from '@cadence/schemas'
+import { interactionDbProvider } from './interaction-db-provider.ts'
+import { contactDbProvider } from '../contact/contact-db-provider.ts'
+
+const log = Log.channel('interaction')
+
+const Profile = UserSchemas.profileModel
+
+// ─── Errors ────────────────────────────────────────────────────────────────────
+
+export const InteractionNotFoundError = CustomErrors.create({
+  name: 'InteractionNotFoundError',
+  message: 'Interaction not found',
+  httpStatusCode: 'notFound' as const
+})
+
+export const ContactNotFoundError = CustomErrors.create({
+  name: 'ContactNotFoundError',
+  message: 'Contact not found',
+  httpStatusCode: 'notFound' as const
+})
+
+export const ForbiddenError = CustomErrors.create({
+  name: 'ForbiddenError',
+  message: 'You do not have permission to perform this action',
+  httpStatusCode: 'forbidden' as const
+})
+
+export const EmptyBodyError = CustomErrors.create({
+  name: 'EmptyBodyError',
+  message: 'Interaction body must not be empty',
+  httpStatusCode: 'unprocessableContent' as const
+})
+
+export const BodyTooLongError = CustomErrors.create({
+  name: 'BodyTooLongError',
+  message: 'Interaction body must not exceed 50,000 characters',
+  httpStatusCode: 'unprocessableContent' as const
+})
+
+// ─── HTML Helpers ──────────────────────────────────────────────────────────────
+
+const sanitizeConfig: sanitize.IOptions = {
+  allowedTags: [
+    'b', 'strong', 'i', 'em', 's', 'strike', 'del',
+    'p', 'br', 'hr', 'ul', 'ol', 'li', 'a',
+    'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+    'blockquote', 'pre', 'code'
+  ],
+  allowedAttributes: { a: ['href', 'target', 'rel'] }
+}
+
+function validateBody(body: string): string {
+  if (body.length > 50000) throw new BodyTooLongError()
+
+  const textContent = sanitize(body, { allowedTags: [], allowedAttributes: {} }).trim()
+  if (textContent.length === 0) throw new EmptyBodyError()
+
+  return sanitize(body, sanitizeConfig)
+}
+
+// ─── Use Cases ─────────────────────────────────────────────────────────────────
+
+export const LogInteraction = z
+  .function({
+    input: [InteractionSchemas.createInteractionForm, Profile]
+  })
+  .implement(async ({ contactId, type, subject, body, date }, profile) => {
+    Permissions.gate(profile, 'interaction', 'create')
+
+    const contact = await contactDbProvider.getById(contactId)
+    if (!contact) throw new ContactNotFoundError()
+    if (contact.organizationId !== profile.organizationId) throw new ContactNotFoundError()
+
+    const sanitizedBody = validateBody(body)
+
+    const interactionId = await interactionDbProvider.create({
+      contactId,
+      userId: profile.userId,
+      type,
+      subject: subject ?? null,
+      body: sanitizedBody,
+      date
+    })
+
+    log.info('Interaction logged', {
+      action: 'interaction.log',
+      userId: profile.userId,
+      interactionId,
+      contactId,
+      type
+    })
+
+    return { interactionId }
+  })
+
+export const EditInteraction = z
+  .function({
+    input: [InteractionSchemas.editInteractionForm.extend({ interactionId: z.number() }), Profile]
+  })
+  .implement(async ({ interactionId, type, subject, body, date }, profile) => {
+    Permissions.gate(profile, 'interaction', 'update')
+
+    const interaction = await interactionDbProvider.getById(interactionId)
+    if (!interaction) throw new InteractionNotFoundError()
+
+    const contact = await contactDbProvider.getById(interaction.contactId)
+    if (!contact || contact.organizationId !== profile.organizationId) throw new InteractionNotFoundError()
+
+    if (interaction.userId !== profile.userId && profile.role !== 'admin') {
+      throw new ForbiddenError()
+    }
+
+    const sanitizedBody = validateBody(body)
+
+    await interactionDbProvider.update(interactionId, {
+      type,
+      subject: subject ?? null,
+      body: sanitizedBody,
+      date
+    })
+
+    log.info('Interaction edited', {
+      action: 'interaction.edit',
+      userId: profile.userId,
+      interactionId
+    })
+  })
+
+export const ListRecent = z
+  .function({
+    input: [z.object({}), Profile]
+  })
+  .implement(async (_data, profile) => {
+    Permissions.gate(profile, 'interaction', 'list')
+
+    const interactions = await interactionDbProvider.listRecent(profile.organizationId)
+
+    return { interactions }
+  })
+
+export const DeleteInteraction = z
+  .function({
+    input: [z.object({ interactionId: z.number() }), Profile]
+  })
+  .implement(async ({ interactionId }, profile) => {
+    Permissions.gate(profile, 'interaction', 'delete')
+
+    const interaction = await interactionDbProvider.getById(interactionId)
+    if (!interaction) throw new InteractionNotFoundError()
+
+    const contact = await contactDbProvider.getById(interaction.contactId)
+    if (!contact || contact.organizationId !== profile.organizationId) throw new InteractionNotFoundError()
+
+    if (interaction.userId !== profile.userId && profile.role !== 'admin') {
+      throw new ForbiddenError()
+    }
+
+    await interactionDbProvider.softDelete(interactionId)
+
+    log.info('Interaction deleted', {
+      action: 'interaction.delete',
+      userId: profile.userId,
+      interactionId
+    })
+  })

package/skills/maestro-examples/references/cadence/packages/services/src/maestro.ts

@@ -0,0 +1,218 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { Db } from '@maestro-js/db'
+import { Cache } from '@maestro-js/cache'
+import { Hash } from '@maestro-js/hash'
+import { Crypt } from '@maestro-js/crypt'
+import { Auth } from '@maestro-js/auth'
+import { Password, PasswordReset } from '@maestro-js/password'
+import { Session } from '@maestro-js/session'
+import { RateLimiting } from '@maestro-js/rate-limiting'
+import { Queue } from '@maestro-js/queue'
+import { RecurringJobs } from '@maestro-js/recurring-jobs'
+import { Mail } from '@maestro-js/mail'
+import { Log } from '@maestro-js/log'
+import { Permissions } from '@maestro-js/permissions'
+import type { Helpers } from '@maestro-js/helpers'
+import { SESClient, SendRawEmailCommand, type SendRawEmailCommandInput } from '@aws-sdk/client-ses'
+import type { UserSchemas } from '@cadence/schemas'
+import { authDbProvider } from './auth/auth-db-provider.ts'
+import { permissionsDriver, type ActionMap } from './permissions.ts'
+
+type Credentials = { orgSlug: string; email: string; password: string }
+export type DeviceContext = ReturnType<(typeof Helpers)['getDeviceContext']>
+
+Db.Provider.register(
+  'default',
+  Db.Provider.create({
+    driver: Db.drivers.mysql({
+      user: process.env.DB_USER!,
+      password: process.env.DB_PASSWORD!,
+      host: process.env.DB_HOST!,
+      database: process.env.DB_DATABASE!,
+      port: Number(process.env.DB_PORT!)
+    })
+  })
+)
+
+Cache.Provider.register(
+  'default',
+  Cache.Provider.create({
+    driver:
+      process.env.ENV_NAME === 'local'
+        ? Cache.drivers.mockRedis({})
+        : Cache.drivers.redis({ url: process.env.REDIS_URL!, port: Number(process.env.REDIS_PORT!) })
+  })
+)
+
+Hash.Provider.register(
+  'default',
+  Hash.Provider.create(Hash.drivers.sha256({ key: process.env.HASH_KEY!, previousKeys: [] }))
+)
+Hash.Provider.register('bcrypt', Hash.Provider.create(Hash.drivers.bcrypt({ rounds: 12 })))
+
+Password.Provider.register(
+  'default',
+  Password.Provider.create<number, Credentials>({
+    getAuthenticatableByCredentials: authDbProvider.getAuthenticatableByCredentials,
+    updatePasswordHash: authDbProvider.updatePasswordHash,
+    updateCredentialsInvalidBefore: authDbProvider.updateCredentialsInvalidBefore,
+    hash: Hash.provider('bcrypt'),
+    passwordReset: PasswordReset.create<number>({
+      ...authDbProvider.passwordResetToken,
+      hash: Hash.provider('bcrypt')
+    })
+  })
+)
+
+Auth.Provider.register(
+  'default',
+  Auth.Provider.create<number, Credentials, DeviceContext>({
+    name: 'default',
+    getAuthenticatableById: authDbProvider.getAuthenticatableById,
+    verifyCredentials: Password.verifyCredentials,
+    updateCredentialsInvalidBefore: authDbProvider.updateCredentialsInvalidBefore,
+    hash: Hash,
+    crypt: Crypt,
+    rememberMeOptions: {
+      maxRememberMeSeconds: 60 * 60 * 24 * 30 /* thirty days */,
+      ...authDbProvider.rememberMeToken
+    }
+  })
+)
+
+Crypt.Provider.register(
+  'default',
+  Crypt.Provider.create({
+    key: process.env.ENCRYPTION_KEY!,
+    previousKeys: []
+  })
+)
+
+Session.Provider.register(
+  'default',
+  Session.Provider.create({
+    driver: Session.drivers.store({
+      store: Cache,
+      crypt: Crypt,
+      cookie: {
+        name: 'cadence_session',
+        secure: process.env.ENV_NAME !== 'local',
+        httpOnly: true,
+        sameSite: 'Lax',
+        maxAge: 30 * 24 * 60 * 60
+      }
+    })
+  })
+)
+
+RateLimiting.Provider.register('default', RateLimiting.Provider.create(Cache))
+
+Queue.Provider.register(
+  'default',
+  Queue.Provider.create({
+    driver: Queue.drivers.db({
+      db: Db,
+      databaseTable: 'queueMessages'
+    }),
+    logger: Log
+  })
+)
+
+RecurringJobs.Provider.register(
+  'default',
+  RecurringJobs.Provider.create({
+    driver: RecurringJobs.drivers.db({
+      db: Db,
+      databaseTable: 'recurringJobs'
+    }),
+    logger: Log
+  })
+)
+
+if (process.env.ENV_NAME === 'local') {
+  const e2eMailDir = path.resolve(process.cwd(), '.e2e-mail')
+  fs.mkdirSync(e2eMailDir, { recursive: true })
+  Mail.Provider.register(
+    'default',
+    Mail.Provider.create({
+      driver: Mail.drivers.stub({
+        logger: {
+          info(envelope: Mail.Envelope) {
+            fs.writeFileSync(path.join(e2eMailDir, 'latest.json'), JSON.stringify(envelope, null, 2))
+          }
+        } as any
+      }),
+      name: 'default',
+      globalFrom: process.env.MAIL_FROM!,
+      logger: Log,
+      queue: Queue
+    })
+  )
+} else {
+  const sesClient = new SESClient({ region: process.env.AWS_REGION! })
+  Mail.Provider.register(
+    'default',
+    Mail.Provider.create({
+      driver: Mail.drivers.ses({
+        send(command: { input: SendRawEmailCommandInput }) {
+          return sesClient.send(new SendRawEmailCommand(command.input))
+        },
+        configurationSetName: 'cadence'
+      }),
+      name: 'default',
+      globalFrom: process.env.MAIL_FROM!,
+      logger: Log,
+      queue: Queue
+    })
+  )
+}
+
+Log.addTransport(Log.transports.console())
+
+Permissions.Provider.register('default', Permissions.Provider.create({ driver: permissionsDriver }))
+
+declare module '@maestro-js/password' {
+  namespace Password {
+    namespace Provider {
+      interface Keys {
+        default: { Id: number; Credentials: Credentials }
+      }
+    }
+  }
+}
+
+declare module '@maestro-js/auth' {
+  namespace Auth {
+    namespace Provider {
+      interface Keys {
+        default: {
+          Credentials: Credentials
+          DeviceContext: DeviceContext
+          Id: number
+        }
+      }
+    }
+  }
+}
+
+declare module '@maestro-js/hash' {
+  namespace Hash {
+    namespace Provider {
+      interface Keys {
+        default: true
+        bcrypt: true
+      }
+    }
+  }
+}
+
+declare module '@maestro-js/permissions' {
+  namespace Permissions {
+    namespace Provider {
+      interface Keys {
+        default: { ActionMap: ActionMap; Profile: UserSchemas.profileModel | null }
+      }
+    }
+  }
+}

package/skills/maestro-examples/references/cadence/packages/services/src/organization/index.ts

@@ -0,0 +1,8 @@
+import { CreateOrganization, ViewOrganization, EditOrganization, DeleteOrganization } from './organization-use-cases.ts'
+
+export const OrganizationService = {
+  CreateOrganization,
+  ViewOrganization,
+  EditOrganization,
+  DeleteOrganization
+}