@elevasis/sdk 1.4.0 → 1.5.0

package/reference/scaffold/operations/workflow-recipes.md

@@ -0,0 +1,419 @@
+---
+title: Workflow Recipes
+description: Anatomy of a workflow, adapter usage, and trigger patterns -- runnable email-notification example replaces the trivial echo workflow. Resolves eval score 2/5 on workflow authoring.
+---
+
+# Workflow Recipes
+
+`🟢 Stable` -- Use these patterns as-is against `@elevasis/sdk ^1.4.0`.
+
+---
+
+## 1. Anatomy of a Workflow
+
+Every workflow is a `WorkflowDefinition` object with four top-level keys: `config`, `contract`, `steps`, and `entryPoint`. The `email-notification` workflow at `operations/src/email-notification/index.ts` is used as the running example throughout this section.
+
+### Config
+
+```typescript
+config: {
+  resourceId: 'email-notification', // Unique ID -- used in API calls and CLI
+  name: 'Email Notification',       // Human-readable display name
+  type: 'workflow',                  // Always 'workflow' (vs 'agent')
+  description: 'Sends a notification email to a user...',
+  version: '1.0.0',                  // Bump on contract changes
+  status: 'dev'                      // 'dev' or 'prod'
+}
+```
+
+- `resourceId` is the stable identifier used by `pnpm exec elevasis exec` and `/execute` API calls.
+- Bump `version` whenever you change `contract.inputSchema` or `contract.outputSchema`.
+
+### Contract
+
+```typescript
+// foundations/types/index.ts -- shared with frontend
+export const emailNotificationInputSchema = z.object({
+  recipientEmail: z.string().email(),
+  recipientName: z.string().min(1),
+  subject: z.string().min(1).max(200),
+  body: z.string().min(1).max(10000),
+  category: z.string().min(1).default('operations'),
+  actionUrl: z.string().url().optional()
+})
+
+export const emailNotificationOutputSchema = z.object({
+  delivered: z.boolean(),
+  notificationId: z.string().optional(),
+  summary: z.string()
+})
+
+export type EmailNotificationInput = z.infer<typeof emailNotificationInputSchema>
+export type EmailNotificationOutput = z.infer<typeof emailNotificationOutputSchema>
+```
+
+```typescript
+// operations/src/email-notification/index.ts
+import { emailNotificationInputSchema, emailNotificationOutputSchema } from '@foundation/types'
+
+contract: {
+  inputSchema: emailNotificationInputSchema,
+  outputSchema: emailNotificationOutputSchema
+}
+```
+
+**Rules:**
+
+- Define schemas in `foundations/types/index.ts` -- never inline Zod schemas in workflow files.
+- Both runtimes (frontend and platform) import from `@foundation/types`, keeping validation consistent.
+- `@foundation/types` resolves to `foundations/types/index.ts` via the tsconfig path alias.
+
+### Steps
+
+Each step is a `WorkflowStep` with: `id`, `name`, `description`, `handler`, `inputSchema`, `outputSchema`, and `next`.
+
+```typescript
+import { StepType } from '@elevasis/sdk'
+
+steps: {
+  validate: {
+    id: 'validate',
+    name: 'Validate Input',
+    description: 'Validates recipient and content parameters before sending',
+    handler: async (rawInput, context) => {
+      const input = rawInput as EmailNotificationInput
+      context.logger.info(`[validate] Checking recipient: ${input.recipientEmail}`)
+      // ... validation logic ...
+      return input          // Pass validated data to next step
+    },
+    inputSchema: emailNotificationInputSchema,
+    outputSchema: emailNotificationInputSchema,  // Passes full input through to next step
+    next: { type: StepType.LINEAR, target: 'notify' }
+  },
+  notify: {
+    id: 'notify',
+    name: 'Send Notification',
+    handler: async (rawInput, context) => {
+      // ...
+      return { delivered: true, summary: '...' }
+    },
+    inputSchema: emailNotificationInputSchema,
+    outputSchema: emailNotificationOutputSchema,
+    next: null  // Terminal step -- ends the workflow
+  }
+}
+```
+
+**Key rules:**
+
+- `next: null` marks a terminal step.
+- `next: { type: StepType.LINEAR, target: 'stepId' }` chains to another step.
+- Use `context.logger` -- never `console.log`. Platform captures `context.logger.*` only.
+- Cast `rawInput` to your input type: `const input = rawInput as EmailNotificationInput`.
+
+### Entrypoint
+
+```typescript
+entryPoint: 'validate'   // Must match a step id in the steps map
+```
+
+The platform starts execution here. For single-step workflows, `entryPoint` points to the only step (e.g., `echo` points to `'echo'`).
+
+### Optional: Interface Form
+
+Declare `interface.form` to auto-generate an execution form in AI Studio and Command Center:
+
+```typescript
+interface: {
+  form: {
+    title: 'Send Email Notification',
+    description: 'Sends a notification email to a user.',
+    fields: [
+      { name: 'recipientEmail', label: 'Recipient Email', type: 'text', required: true },
+      { name: 'body', label: 'Body', type: 'text', required: true }
+    ],
+    submitButton: { label: 'Send notification', loadingLabel: 'Sending...' }
+  }
+}
+```
+
+---
+
+## 2. Adapter Usage
+
+Adapters are typed wrappers over `platform.call()`. Import singletons from `@elevasis/sdk/worker`.
+
+### notifications
+
+Send a platform notification to the current user. `userId` and `organizationId` are injected server-side -- you never supply them.
+
+```typescript
+import { notifications } from '@elevasis/sdk/worker'
+
+await notifications.create({
+  category: 'operations',      // Any string: 'operations', 'delivery', 'acquisition', etc.
+  title: 'Workflow complete',
+  message: 'Your email notification was sent successfully.',
+  actionUrl: '/operations'     // Optional -- link the user can follow
+})
+```
+
+Available methods: `create`.
+
+### llm
+
+Generate text or structured output using a language model.
+
+```typescript
+import { llm } from '@elevasis/sdk/worker'
+
+const response = await llm.generate({
+  provider: 'anthropic',          // 'anthropic' | 'openai' | 'openrouter' | 'google'
+  model: 'claude-sonnet-4-5',
+  messages: [
+    { role: 'user', content: 'Summarize this email body: ' + input.body }
+  ]
+})
+
+const summary = response.output as string
+```
+
+For structured output, pass a JSON Schema as `responseSchema`:
+
+```typescript
+const response = await llm.generate({
+  provider: 'anthropic',
+  model: 'claude-sonnet-4-5',
+  messages: [{ role: 'user', content: 'Extract the key action from: ' + input.body }],
+  responseSchema: {
+    type: 'object',
+    properties: { action: { type: 'string' }, urgency: { type: 'string' } }
+  }
+})
+const { action, urgency } = response.output as { action: string; urgency: string }
+```
+
+Available methods: `generate`.
+
+### storage
+
+Upload and retrieve files scoped to the organization. All paths are automatically prefixed with the organization's storage prefix server-side.
+
+```typescript
+import { storage } from '@elevasis/sdk/worker'
+
+// Upload
+await storage.upload({
+  bucket: 'operations',
+  path: 'email-logs/2026-04-16/batch-01.json',
+  content: Buffer.from(JSON.stringify(logData)).toString('base64'),
+  contentType: 'application/json'
+})
+
+// Download
+const file = await storage.download({
+  bucket: 'operations',
+  path: 'email-logs/2026-04-16/batch-01.json'
+})
+
+// Signed URL for frontend access
+const { signedUrl } = await storage.createSignedUrl({
+  bucket: 'operations',
+  path: 'email-logs/2026-04-16/batch-01.json',
+  expiresIn: 3600
+})
+```
+
+Available methods: `upload`, `download`, `createSignedUrl`, `delete`, `list`.
+
+### scheduler
+
+Schedule future or recurring workflow executions.
+
+```typescript
+import { scheduler } from '@elevasis/sdk/worker'
+
+const schedule = await scheduler.createSchedule({
+  name: 'Daily email digest',
+  target: { resourceType: 'workflow', resourceId: 'email-notification' },
+  scheduleConfig: {
+    type: 'cron',
+    expression: '0 9 * * 1-5'  // 9am weekdays
+  }
+})
+
+context.logger.info(`[schedule] Created schedule: ${schedule.id}`)
+```
+
+Available methods: `createSchedule`, `updateAnchor`, `deleteSchedule`, `getSchedule`, `listSchedules`, `cancelSchedule`, `cancelSchedulesByMetadata`, `cancelScheduleByIdempotencyKey`, `findByIdempotencyKey`, `deleteScheduleByIdempotencyKey`.
+
+**Note on other adapters:** Integration adapters (`createResendAdapter`, `createAttioAdapter`, etc.) follow a factory pattern -- bind a credential once, use the instance for all calls:
+
+```typescript
+import { createResendAdapter } from '@elevasis/sdk/worker'
+
+const resend = createResendAdapter('my-resend-credential')
+await resend.sendEmail({
+  to: input.recipientEmail,
+  subject: input.subject,
+  html: `<p>${input.body}</p>`
+})
+```
+
+See `operations/node_modules/@elevasis/sdk/reference/` for the full adapter reference.
+
+---
+
+## 3. Trigger Patterns from Frontend
+
+### (a) API call via `useApiClient`
+
+Use this pattern in React components and hooks. `apiRequest` automatically attaches the auth token and org context.
+
+```typescript
+// ui/src/features/notifications/hooks/useSendEmailNotification.ts
+import { useMutation } from '@tanstack/react-query'
+import { useApiClient } from '@/shared/api'
+import type { EmailNotificationInput, EmailNotificationOutput } from '@foundation/types'
+
+export function useSendEmailNotification() {
+  const { apiRequest } = useApiClient()
+
+  return useMutation({
+    mutationFn: async (input: EmailNotificationInput) => {
+      return apiRequest<EmailNotificationOutput>('/execute', {
+        method: 'POST',
+        body: JSON.stringify({
+          resourceType: 'workflow',
+          resourceId: 'email-notification',
+          input
+        })
+      })
+    }
+  })
+}
+```
+
+Usage in a component:
+
+```tsx
+// ui/src/features/notifications/components/SendNotificationButton.tsx
+import { useSendEmailNotification } from '../hooks/useSendEmailNotification'
+
+function SendNotificationButton() {
+  const { mutate, isPending, isSuccess } = useSendEmailNotification()
+
+  return (
+    <Button
+      loading={isPending}
+      onClick={() =>
+        mutate({
+          recipientEmail: 'user@example.com',
+          recipientName: 'Jane Smith',
+          subject: 'Your request is ready',
+          body: 'Hi Jane, your workflow has completed.',
+          category: 'operations'
+        })
+      }
+    >
+      Send Notification
+    </Button>
+  )
+}
+```
+
+For async execution (long-running workflows), use `/execute-async` instead:
+
+```typescript
+return apiRequest<{ executionId: string }>('/execute-async', {
+  method: 'POST',
+  body: JSON.stringify({
+    resourceType: 'workflow',
+    resourceId: 'email-notification',
+    input
+  })
+})
+// Poll /executions/email-notification/:executionId for status
+```
+
+### (b) Direct SDK dispatch (CLI or scripts)
+
+From the project root, use the platform CLI for manual invocations, testing, and scripting:
+
+```bash
+# Describe the schema before executing
+pnpm exec elevasis describe Elevasis/email-notification
+
+# Execute synchronously
+pnpm exec elevasis exec Elevasis/email-notification --input '{
+  "recipientEmail": "user@example.com",
+  "recipientName": "Jane Smith",
+  "subject": "Hello",
+  "body": "Hi Jane, this is a test notification."
+}'
+
+# Execute asynchronously (for long-running workflows)
+pnpm exec elevasis exec Elevasis/email-notification --async --input '{...}'
+
+# View a specific execution
+pnpm exec elevasis execution Elevasis/email-notification <executionId>
+```
+
+The `--prod` flag targets `https://api.elevasis.io` and goes **before** the command:
+
+```bash
+pnpm exec elevasis --prod exec Elevasis/email-notification --input '{...}'
+```
+
+---
+
+## 4. Registry Pattern
+
+Workflows are discovered through `operations/src/index.ts`, which exports a `DeploymentSpec` as its default export.
+
+**Pattern:** each feature group in `operations/src/` has its own exports barrel. The top-level spec spreads all groups:
+
+```
+operations/src/
+  index.ts                          # Top-level DeploymentSpec -- never add workflows here directly
+  example/
+    index.ts                        # export const workflows = [echo]; export const agents = []
+    echo.ts                         # WorkflowDefinition for 'echo'
+  email-notification/
+    exports.ts                      # export const workflows = [emailNotification]; export const agents = []
+    index.ts                        # WorkflowDefinition for 'email-notification'
+```
+
+Top-level registry (`operations/src/index.ts`):
+
+```typescript
+import type { DeploymentSpec } from '@elevasis/sdk'
+import * as example from './example/index.js'
+import * as emailNotification from './email-notification/exports.js'
+
+const org: DeploymentSpec = {
+  version: '0.1.0',
+  workflows: [...example.workflows, ...emailNotification.workflows],
+  agents: [...example.agents, ...emailNotification.agents]
+}
+export default org
+```
+
+Feature group barrel (e.g., `email-notification/exports.ts`):
+
+```typescript
+import { emailNotification } from './index.js'
+import type { WorkflowDefinition } from '@elevasis/sdk'
+
+export const workflows: WorkflowDefinition[] = [emailNotification]
+export const agents: never[] = []
+```
+
+**Adding a new workflow:**
+
+1. Create `operations/src/<feature>/index.ts` with the `WorkflowDefinition`.
+2. Create `operations/src/<feature>/exports.ts` with `workflows` and `agents` arrays.
+3. Import the group barrel in `operations/src/index.ts` and spread into `workflows`/`agents`.
+4. Run `pnpm -C operations check` to validate, then `pnpm -C operations deploy` to publish.
+
+**Note:** Use `.js` extensions in imports even though the source is TypeScript. The TypeScript compiler and esbuild bundler both require this for ESM interoperability.

package/reference/scaffold/recipes/add-a-feature.md

@@ -0,0 +1,142 @@
+---
+title: Add a Feature
+description: End-to-end walkthrough for adding a new shell feature (e.g., analytics) from org-model key through manifest, routes, and gating.
+---
+
+# Add a Feature
+
+End-to-end: add a new shell feature such as `analytics`. Steps are sequential.
+
+See [glossary.md](../reference/glossary.md) for term disambiguation throughout this recipe (Feature has three distinct contexts). See [contracts.md](../reference/contracts.md) for authoritative TypeScript shapes.
+
+---
+
+## 1. Decide the feature shape
+
+A shell feature requires an `OrganizationModelFeatureKey` to gate it. You have two options:
+
+- **Reuse an existing key** (e.g., `operations`, `monitoring`). The new feature shares an on/off toggle with other features using that key. Fine for sub-features within an existing domain.
+- **Add a new platform key** -- only possible if you are extending `OrganizationModelFeatureKey` itself, which requires a core package change. For template-local keys, use `FoundationLegacyFeatureKey` instead.
+
+For a genuinely new capability (e.g., `analytics`), you will extend `FoundationLegacyFeatureKey` in foundations so it becomes a valid `FoundationFeatureKey` and then declare it in the org model.
+
+See [glossary.md](../reference/glossary.md) under **Feature** (three contexts) and **OrganizationModelFeatureKey**.
+
+---
+
+## 2. Update the organization model
+
+File: `foundations/config/organization-model.ts`
+
+Add the key to `FoundationLegacyFeatureKey`, then declare it under `features.enabled`, `features.labels`, and the `featuresEnabled` resolver map.
+
+```ts
+// 1. Extend the local key union
+type FoundationLegacyFeatureKey = 'crm' | 'lead-gen' | 'projects' | 'analytics'
+
+// 2. Enable in defineOrganizationModel call
+features: {
+  enabled: { ..., analytics: false },  // start disabled
+  labels:  { ..., analytics: 'Analytics' }
+}
+
+// 3. Add to featuresEnabled resolver
+const featuresEnabled: Record<FoundationFeatureKey, boolean> = {
+  ...
+  analytics: resolvedOrganizationModel.features.enabled.analytics ?? false
+}
+```
+
+Optionally, add a new domain entry and a navigation surface. See `OrganizationModelSemanticDomain` and `OrganizationModelSurface` shapes in [contracts.md](../reference/contracts.md).
+
+---
+
+## 3. Author the FeatureModule
+
+Create `ui/src/features/analytics/manifest.ts`. Full `FeatureModule` shape is in [contracts.md](../reference/contracts.md#featuremodule) (`@elevasis/ui/provider`).
+
+```ts
+import type { FeatureModule } from '@elevasis/ui/provider'
+import { IconChartBar } from '@tabler/icons-react'
+import { AnalyticsSidebar } from './sidebar'
+
+export const analyticsManifest: FeatureModule = {
+  key: 'analytics',
+  accessFeatureKey: 'analytics',     // must match a FoundationFeatureKey
+  navEntry: {
+    label: 'Analytics',
+    icon: IconChartBar,
+    link: '/analytics'
+  },
+  sidebar: AnalyticsSidebar,
+  subshellRoutes: ['/analytics', '/analytics/reports']
+}
+```
+
+Key fields:
+
+- `accessFeatureKey` -- the org-model key that gates the entire feature. The provider throws at startup if this key is not declared. See [glossary.md](../reference/glossary.md) under **accessFeatureKey**.
+- `sidebar` -- a component that renders the subshell sidebar. Compose from published primitives. See [customization.md](../ui/customization.md).
+- `subshellRoutes` -- every path that should activate this feature's sidebar.
+
+Register the manifest in `ui/src/routes/__root.tsx` by adding it to the `FEATURE_MANIFESTS` array passed to `ElevasisFeaturesProvider`.
+
+---
+
+## 4. Add routes under the subshell
+
+Create the TanStack Router layout and child routes.
+
+Layout file (`ui/src/routes/analytics.tsx`) owns the subshell guard and renders `<Outlet />`:
+
+```tsx
+import { createFileRoute, Outlet } from '@tanstack/react-router'
+import { ProtectedRoute } from '@/features/auth'
+import { FeatureGuard } from '@/features/auth/guards/FeatureGuard'
+
+export const Route = createFileRoute('/analytics')({
+  component: AnalyticsLayout
+})
+
+function AnalyticsLayout() {
+  return (
+    <ProtectedRoute>
+      <FeatureGuard featureKey="analytics">
+        <Outlet />
+      </FeatureGuard>
+    </ProtectedRoute>
+  )
+}
+```
+
+Child pages go under `ui/src/routes/analytics/`. See [UI Recipes](../ui/recipes.md) recipe 2 for the nested page pattern.
+
+---
+
+## 5. Gate the route
+
+Two independent mechanisms -- use both:
+
+- `FeatureGuard` (feature-level): blocks access when the org model has the feature key disabled or when the member's `MembershipFeatureConfig` disables it. Always nest inside `ProtectedRoute`.
+- `AdminGuard` (admin-level): blocks access for non-admin members. Add this if the feature should only be accessible to admins.
+
+Full decision table and import paths are in [gate-by-feature-or-admin.md](gate-by-feature-or-admin.md).
+
+---
+
+## 6. (Optional) Add operations resources that back the feature
+
+If the feature drives automation (e.g., an analytics pipeline workflow), create the resources in `operations/src/` and optionally map them into the org model via `resourceMappings`. See [add-a-resource.md](add-a-resource.md).
+
+---
+
+## 7. Verify
+
+```bash
+pnpm -C ui dev
+```
+
+- Feature appears in the nav sidebar.
+- Route is accessible and the subshell sidebar renders.
+- Toggle `features.enabled.analytics` to `false` in `foundations/config/organization-model.ts` and confirm the nav item disappears and the route redirects.
+- Check `FeatureGuard` by navigating directly to `/analytics` with the feature disabled.