skedyul 1.4.11 → 1.5.2

package/README.md

@@ -1,19 +1,21 @@
 # skedyul
 
-The official Node.js SDK for building Skedyul integration apps. This package provides everything you need to create MCP (Model Context Protocol) servers, handle webhooks, manage lifecycle events, and interact with the Skedyul platform.
+The official Node.js SDK for building [Skedyul](https://skedyul.com) integration apps. Publish tools, webhooks, CRM models, agents, skills, and workflows — then run them on serverless (Lambda) or dedicated (Docker/ECS) compute.
 
-## Version 1.0.0
+**Package:** `skedyul` · **Version:** 1.4.x · **Node:** 22+
 
-This release introduces a modular, file-based configuration system with improved type safety and developer experience.
+## What you can build
 
-## Features
-
-- **MCP Server**: Build tools that AI agents can invoke via the Model Context Protocol
-- **Webhooks**: Receive and process external events (SMS, emails, API callbacks)
-- **Lifecycle Hooks**: Handle app installation, provisioning, and cleanup
-- **Core API Client**: Interact with Skedyul resources (workplaces, channels, instances)
-- **CLI**: Develop and test locally with hot-reload and tunneling
-- **Modular Config**: File-based configuration with auto-discovery patterns
+| Capability | Description |
+|------------|-------------|
+| **MCP tools** | Functions AI agents invoke via the Model Context Protocol |
+| **Webhooks** | HTTP handlers for SMS, email, OAuth callbacks, and third-party events |
+| **Lifecycle hooks** | Install, provision, uninstall, and OAuth flows |
+| **CRM models** | App-owned (internal) and user-mapped (shared) data models |
+| **Agents (v3)** | Skills-based autonomous agents deployed per workplace |
+| **Skills & workflows** | YAML-defined capabilities and event-driven automation |
+| **Core API client** | Typed client for workplaces, channels, instances, files, cron, AI, calls, and more |
+| **CLI** | Local dev server, tunneling, deploy, CRM schema sync, agent testing |
 
 ## Installation
 
@@ -23,19 +25,24 @@ npm install skedyul
 pnpm add skedyul
 ```
 
-## Quick Start
+The CLI is included:
+
+```bash
+skedyul --help
+```
+
+## Quick start
 
-### 1. Create your configuration
+### 1. Create `skedyul.config.ts`
 
 ```ts
-// skedyul.config.ts
 import { defineConfig } from 'skedyul'
 import pkg from './package.json'
 
 export default defineConfig({
   name: 'My Integration',
   version: pkg.version,
-  description: 'Description of what this app does',
+  description: 'What this app does',
   computeLayer: 'serverless',
 
   tools: import('./src/registries'),
@@ -44,67 +51,31 @@ export default defineConfig({
 })
 ```
 
-### 2. Define your provision config
+### 2. Aggregate provision config
 
 ```ts
 // provision.ts
 import type { ProvisionConfig } from 'skedyul'
-
 import env from './env'
 import { models, relationships } from './crm'
 import * as channels from './channels'
 import * as pages from './pages'
 import navigation from './pages/navigation'
 
-const config: ProvisionConfig = {
+export default {
   env,
   navigation,
   models: Object.values(models),
   channels: Object.values(channels),
   pages: Object.values(pages),
   relationships,
-}
-
-export default config
+} satisfies ProvisionConfig
 ```
 
-### 3. Define a model
+### 3. Define a tool
 
 ```ts
-// crm/models/contact.ts
-import { defineModel } from 'skedyul'
-
-export default defineModel({
-  handle: 'contact',
-  label: 'Contact',
-  labelPlural: 'Contacts',
-  scope: 'shared',
-
-  fields: [
-    {
-      handle: 'name',
-      label: 'Name',
-      type: 'string',
-      required: true,
-      owner: 'workplace',
-    },
-    {
-      handle: 'email',
-      label: 'Email',
-      type: 'string',
-      required: false,
-      owner: 'workplace',
-    },
-  ],
-})
-```
-
-### 4. Define a tool
-
-```ts
-// src/tools/hello.ts
-import { z } from 'skedyul'
-import type { ToolHandler, ToolDefinition } from 'skedyul'
+import { z, type ToolHandler, type ToolDefinition } from 'skedyul'
 
 const inputSchema = z.object({
   name: z.string().optional(),
@@ -113,13 +84,11 @@ const inputSchema = z.object({
 type Input = z.infer<typeof inputSchema>
 type Output = { message: string }
 
-const handler: ToolHandler<Input, Output> = async (input, context) => {
-  return {
-    output: { message: `Hello, ${input.name ?? 'world'}!` },
-    billing: { credits: 1 },
-    meta: { success: true, message: 'Greeting sent', toolName: 'hello' },
-  }
-}
+const handler: ToolHandler<Input, Output> = async (input) => ({
+  output: { message: `Hello, ${input.name ?? 'world'}!` },
+  billing: { credits: 1 },
+  meta: { success: true, message: 'Greeting sent', toolName: 'hello' },
+})
 
 export const helloTool: ToolDefinition<Input, Output> = {
   name: 'hello',
@@ -129,228 +98,176 @@ export const helloTool: ToolDefinition<Input, Output> = {
 }
 ```
 
-### 5. Start the server
-
-```ts
-// src/server.ts
-import { server } from 'skedyul'
-import { toolRegistry } from './tools/registry'
-
-const mcpServer = server.create(
-  {
-    computeLayer: 'dedicated',
-    metadata: { name: 'my-integration', version: '1.0.0' },
-  },
-  toolRegistry,
-)
+### 4. Build and run locally
 
-await mcpServer.listen(3000)
+```bash
+skedyul auth login
+skedyul dev link --workplace my-clinic
+skedyul build
+skedyul dev serve --workplace my-clinic
 ```
 
-## Documentation
+See [Local development](./docs/cli.md#local-development) for the full workflow.
 
-| Guide | Description |
-|-------|-------------|
-| [Authentication](./docs/authentication.md) | Token types, scopes, and configuration |
-| [Tools](./docs/tools.md) | Building MCP tools with handlers and schemas |
-| [Webhooks](./docs/webhooks.md) | Receiving external events and callbacks |
-| [Lifecycle Hooks](./docs/lifecycle-hooks.md) | Install, provision, and uninstall handlers |
-| [Core API](./docs/core-api.md) | Client for Skedyul platform resources |
-| [Configuration](./docs/configuration.md) | skedyul.config.ts reference |
-| [Errors](./docs/errors.md) | Error types and handling patterns |
+## Package exports
 
-## Project Structure
+| Import path | Use case |
+|-------------|----------|
+| `skedyul` | Main SDK — config, tools, webhooks, Core API, schemas |
+| `skedyul/serverless` | AWS Lambda handler entry |
+| `skedyul/dedicated` | Long-running HTTP server entry |
+| `skedyul/schemas/agent-schema-v3` | Agent YAML v3 types and validation |
+| `skedyul/schemas/agent-schema` | Legacy multi-stage agent schema |
+| `skedyul/skills/types` | Skill YAML types |
+| `skedyul/scheduling` | Workflow-safe time windows and wait calculations |
+| `skedyul/cli/utils/auth` | CLI auth helpers (for monorepo tooling) |
 
-The recommended project structure uses modular, file-based configuration:
+## Server modes
 
-```
-my-app/
-├── skedyul.config.ts          # App metadata + imports
-├── provision.ts               # Aggregates all modular configs
-├── env.ts                     # Environment variables
-├── crm/
-│   ├── index.ts               # Re-exports models + relationships
-│   ├── relationships.ts       # Model relationships
-│   └── models/
-│       ├── index.ts
-│       └── contact.ts
-├── channels/
-│   ├── index.ts
-│   └── phone.ts
-├── pages/
-│   ├── index.ts
-│   ├── navigation.ts          # Root navigation
-│   └── settings/
-│       └── page.ts
-└── src/
-    └── registries.ts          # Tools and webhooks
-```
-
-## Server Modes
-
-### Dedicated (Docker/ECS)
-
-Long-running HTTP server with request counting and graceful shutdown:
+### Serverless (Lambda)
 
 ```ts
-const mcpServer = server.create(
-  {
-    computeLayer: 'dedicated',
-    metadata: { name: 'my-app', version: '1.0.0' },
-    defaultPort: 3000,
-    maxRequests: 1000,
-    ttlExtendSeconds: 3600,
-  },
-  toolRegistry,
-  webhookRegistry,
-)
+import { server } from 'skedyul'
+import config from './skedyul.config'
 
-await mcpServer.listen()
-```
+const mcpServer = server.create({
+  ...config,
+  computeLayer: 'serverless',
+  tools: toolRegistry,
+  webhooks: webhookRegistry,
+})
 
-### Serverless (AWS Lambda)
+export const handler = mcpServer.handler
+```
 
-Export a Lambda handler with automatic CORS:
+Or use the dedicated subpath export:
 
 ```ts
-const mcpServer = server.create(
-  {
-    computeLayer: 'serverless',
-    metadata: { name: 'my-app', version: '1.0.0' },
-    cors: { allowOrigin: '*' },
-  },
-  toolRegistry,
-  webhookRegistry,
-)
-
-export const handler = mcpServer.handler
+import { handler } from 'skedyul/serverless'
 ```
 
-## Endpoints
+### Dedicated (Docker / ECS)
 
-| Endpoint | Method | Description |
-|----------|--------|-------------|
-| `/mcp` | POST | MCP JSON-RPC (tools/list, tools/call) |
-| `/webhooks/{name}` | * | Webhook handlers |
-| `/health` | GET | Server health status |
-| `/estimate` | POST | Billing estimation |
-| `/install` | POST | Installation handler |
-| `/provision` | POST | Provisioning handler |
-| `/uninstall` | POST | Uninstall handler |
-| `/oauth_callback` | POST | OAuth callback handler |
-
----
+```ts
+const mcpServer = server.create({
+  ...config,
+  computeLayer: 'dedicated',
+  defaultPort: 3000,
+  tools: toolRegistry,
+  webhooks: webhookRegistry,
+})
 
-# Skedyul CLI
+await mcpServer.listen()
+```
 
-The CLI provides local development tools for building and testing Skedyul apps.
+See [Server runtime](./docs/server.md) for endpoints, hooks, and compute-layer differences.
 
-## Quick Start
+## Documentation
 
-```bash
-# 1. Authenticate with Skedyul
-skedyul auth login
+Full documentation lives in [`docs/`](./docs/README.md).
 
-# 2. Navigate to your app directory
-cd integrations/my-app
+### Getting started
 
-# 3. Link to a workplace
-skedyul dev link --workplace my-clinic
+| Guide | Description |
+|-------|-------------|
+| [Configuration](./docs/configuration.md) | `skedyul.config.ts` reference — models, channels, pages, env, queues |
+| [Tools](./docs/tools.md) | Building MCP tools with Zod schemas and handlers |
+| [Webhooks](./docs/webhooks.md) | Receiving external events and lifecycle hooks on channels |
+| [Lifecycle hooks](./docs/lifecycle-hooks.md) | Install, provision, uninstall, OAuth |
+| [Authentication](./docs/authentication.md) | Token types, scopes, and SDK configuration |
+| [Core API](./docs/core-api.md) | Platform resource client reference |
+| [Errors](./docs/errors.md) | Install and runtime error types |
 
-# 4. Start the local development server
-skedyul dev serve --workplace my-clinic
-```
+### Platform features
 
-The CLI will:
-- Prompt for any missing environment variables
-- Start an ngrok tunnel automatically
-- Register your local machine with Skedyul
-- Route tool calls to your local server
+| Guide | Description |
+|-------|-------------|
+| [Agents, skills & workflows](./docs/agents.md) | Agent YAML v3, skills, workflow YAML, compiler, context |
+| [CRM schema](./docs/crm-schema.md) | Workplace-level schema migrations (`defineSchema`) |
+| [Rate-limit queues](./docs/rate-limit-queues.md) | `queuedFetch` for external API throttling |
+| [Server runtime](./docs/server.md) | HTTP endpoints, dedicated vs serverless, MCP protocol |
+| [CLI reference](./docs/cli.md) | All `skedyul` commands and flags |
 
-## Commands
+## Project structure
 
-### Authentication
+Recommended layout for a modular integration app:
 
-```bash
-skedyul auth login     # Log in via browser OAuth
-skedyul auth status    # Check authentication status
-skedyul auth logout    # Log out
 ```
-
-### Configuration
-
-```bash
-skedyul config set <key> <value>  # Set global configuration
-skedyul config get <key>          # Get a config value
-skedyul config list               # List all configuration
+my-app/
+├── skedyul.config.ts       # App metadata, registries, build, queues
+├── provision.ts            # Aggregates version-level config
+├── install.ts              # Optional per-installation config (shared models)
+├── env.ts                  # Environment variable definitions
+├── crm/
+│   ├── index.ts
+│   ├── relationships.ts
+│   └── models/
+├── channels/
+├── pages/
+├── agents/                 # Agent YAML v3 files (deployed via CLI)
+├── skills/                 # Skill YAML files
+├── workflows/              # Workflow YAML v2 files
+└── src/
+    ├── registries.ts       # Tool and webhook registries
+    └── server.ts           # Optional custom server entry
 ```
 
-| Key | Description | Default |
-|-----|-------------|---------|
-| `defaultServer` | Skedyul server URL | `https://admin.skedyul.it` |
-| `ngrokAuthtoken` | Your ngrok authtoken | - |
-
-### Development
+## CLI overview
 
 ```bash
-skedyul dev link --workplace <subdomain>    # Link to a workplace
-skedyul dev unlink --workplace <subdomain>  # Remove a link
-skedyul dev serve --workplace <subdomain>   # Start dev server
-skedyul dev invoke <tool-name>              # Test a single tool
-skedyul dev tools                           # List all tools
-skedyul dev validate                        # Validate config
-skedyul dev diff                            # Preview deploy changes
+# Authentication
+skedyul auth login
+skedyul auth use <profile>
+
+# Local development (linked mode)
+skedyul dev link --workplace <subdomain>
+skedyul dev install --workplace <subdomain>
+skedyul build
+skedyul dev serve --workplace <subdomain>
+
+# Deploy
+skedyul dev diff --workplace <subdomain>
+skedyul dev deploy --workplace <subdomain>
+
+# Agents, skills, workflows
+skedyul agents deploy --file ./agents/booking.yaml --workplace <subdomain>
+skedyul skills deploy --file ./skills/scheduling.yaml --workplace <subdomain>
+skedyul workflows deploy --file ./workflows/reminder.yaml --workplace <subdomain>
+
+# Testing
+skedyul chat --agent booking --workplace <subdomain>
+skedyul dev invoke my_tool --workplace <subdomain>
 ```
 
-### Serve Options
-
-| Flag | Description |
-|------|-------------|
-| `--workplace, -w` | Workplace subdomain (enables sidecar mode) |
-| `--port, -p` | Port to listen on (default: 60000) |
-| `--registry, -r` | Path to registry file |
-| `--no-tunnel` | Don't start ngrok tunnel |
-| `--tunnel-url` | Use existing tunnel URL |
-| `--env, -e` | Set environment variable |
-| `--env-file` | Load env vars from file |
+See [CLI reference](./docs/cli.md) for every command, flag, and config file path.
 
-## Configuration Files
+## Configuration files
 
 | File | Purpose |
 |------|---------|
-| `~/.skedyul/credentials.json` | Authentication tokens |
-| `~/.skedyul/config.json` | Global configuration |
-| `.skedyul.local.json` | Local project overrides |
-| `.skedyul/links/{workplace}.json` | Per-workplace link config |
-| `.skedyul/env/{workplace}.env` | Per-workplace env vars |
-
-## Ngrok Setup
-
-1. Get a free authtoken at [ngrok.com](https://dashboard.ngrok.com/get-started/your-authtoken)
-2. Set it: `skedyul config set ngrokAuthtoken <your-token>`
+| `~/.skedyul/profiles.json` | Auth profiles (multi-server support) |
+| `~/.skedyul/config.json` | Global CLI config (`defaultServer`, `ngrokAuthtoken`) |
+| `.skedyul.local.json` | Project-level server URL override |
+| `.skedyul/links/<workplace>.json` | Per-workplace link config |
+| `.skedyul/env/<workplace>.env` | Per-workplace environment variables |
 
-## Troubleshooting
-
-| Issue | Solution |
-|-------|----------|
-| "Not linked to {workplace}" | Run `skedyul dev link --workplace {workplace}` |
-| "Authentication required" | Run `skedyul auth login` |
-| Port already in use | Use `--port 8080` or let CLI auto-increment |
-| ngrok auth failed | Run `skedyul config set ngrokAuthtoken <token>` |
-
----
-
-## Development
+## Development (this package)
 
 ```bash
-npm run build   # Compile TypeScript
-npm test        # Run tests
+pnpm install
+pnpm build    # Compile TypeScript + bundle with tsup
+pnpm test     # Node test runner
 ```
 
 ## Contributing
 
-1. Follow TypeScript style (strict types, async/await)
-2. Keep MCP transports lean
-3. Add unit tests under `tests/`
+1. Use strict TypeScript — no `any`
+2. Keep MCP transports lean; shared logic belongs in `src/server/route-handlers`
+3. Add unit tests under `tests/` for new behavior
+4. Update docs in `docs/` when adding public APIs or CLI commands
 
 Open a PR with a clear summary for review.
+
+## License
+
+MIT